Tech Arsenal 1

home *** CD-ROM | disk | FTP | other *** search

/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / castools.zip / TKMANUAL.TXT < prev next >

Wrap

Text File | 1990-03-13 | 195KB | 8,449 lines

Programmer's Toolkit for CAS and the Phonebook Version 1.0B Copyright π 1990. All rights reserved. Intel Corporation 5200 N.E. Elam Young Pkwy. Hillsboro, OR 97124-6497 Intel Part Number: 302638-001A Intel Corporation developed this Toolkit. Although this Toolkit has been released into the public domain and is not confidential or proprietary, it is still the copyright and property of Intel Corporation. DISCLAIMER OF WARRANTY INTEL CORPORATION EXCLUDES ANY AND ALL IMPLIED WARRANTIES, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. INTEL DOES NOT MAKE ANY WARRANTY OF REPRESENTATION, EITHER EXPRESSED OR IMPLIED, WITH RESPECT TO THIS TOOLKIT, ITS QUALITY, PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. INTEL SHALL NOT HAVE ANY LIABILITY FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RESULTING FROM THE USE OR MODIFICATION OF THIS TOOLKIT. This manual uses the following trademarks: Connection CoProcessor is a trademark and Intel is a registered trademark of Intel Corporation. Other brand and product names are trademarks of their respective owners. TABLE OF CONTENTS 1 ABOUT THIS MANUAL How To Use This Manual .............................. 1-1 Conventions ......................................... 1-2 2 GETTING STARTED Toolkit Requirements ................................ 2-1 What's On The Diskette? ............................. 2-2 Which Library To Use ................................ 2-3 Installing The Toolkit .............................. 2-5 Modifying The Libraries ............................. 2-5 3 OVERVIEW OF CAS AND THE TOOLKIT Resident Manager .................................... 3-1 Queues and Events ................................... 3-1 Control Files and File Transfer Records (FTRs) ...... 3-2 Event Handles ....................................... 3-3 Toolkit Data Structures and Error Handling .......... 3-3 The Include Files ................................. 3-3 CAS Structures .................................... 3-4 Additional Structures ............................. 3-5 Error Handling .................................... 3-5 Memory Allocation ................................... 3-6 4 CASLIB: C LIBRARY FOR CAS DEVELOPERS Compiling and Linking With CASLIB ................... 4-1 CASLIB Functions Grouped by Operation ............... 4-2 Configuration ..................................... 4-2 Event and Queue Queries ........................... 4-2 Event Creation .................................... 4-3 Event Manipulation ................................ 4-3 File Management ................................... 4-3 CASAbortCurrentEvent (02H) .......................... 4-4 CASAutoReceiveState (0FH) ........................... 4-6 CASDeleteAllFiles (09H) ............................. 4-8 CASDeleteFile (08H) ................................. 4 10 CASFindFirst (05H) .................................. 4-12 CASFindNext (06H) ................................... 4-14 CASGetCurrentEventStatus (10H) ...................... 4-16 CASGetEventDate (0AH) ............................... 4-18 iii iii CASGetEventTime (0CH) ............................... 4-20 CASGetExternalData (0EH) ............................ 4-22 CASGetHardwareStatus (12H) .......................... 4-23 CASGetInstalledState (05H) .......................... 4-25 CASGetQueueStatus (11H) ............................. 4-27 CASMoveReceivedFile (14H) ........................... 4-29 CASOpenFile (07H) ................................... 4-31 CASRunDiagnostics (13H) ............................. 4-33 CASSetTaskDate (0BH) ................................ 4-35 CASSetTaskTime (0DH) ................................ 4-37 CASSubmitSingleFile (15H) ........................... 4-39 CASSubmitTask (01H) ................................. 4-41 CASUnloadResidentManager (16H) ...................... 4-43 5 FAXLIB: HIGH-LEVEL LIBRARY FOR CAS DEVELOPERS Compiling and Linking With FAXLIB ................... 5-1 FAXLIB Functions Grouped by Operation ............... 5-2 Event Management .................................. 5-2 Event and Queue Queries ........................... 5-3 Error Handling .................................... 5-3 FAXCancelTask ....................................... 5-4 FAXCopyECS .......................................... 5-6 FAXError ............................................ 5-8 FAXFreeECS .......................................... 5-11 FAXGetEventControlInfo .............................. 5-13 FAXGetEventCover .................................... 5-16 FAXGetEventFileInfo ................................. 5-19 FAXSend ............................................. 5-22 FAXSubmitTask ....................................... 5-25 6 PBLIB: LIBRARY FOR PHONEBOOK MANAGEMENT Compiling and Linking With PBLIB .................... 6-2 Phonebook Functions Grouped by Operation ............ 6-2 General Management ................................ 6-2 Entry Queries ..................................... 6-3 Entry Modification ................................ 6-3 Phonebook Buffering................................... 6-3 PbAddEntry .......................................... 6-4 PbAddToGroup.......................................... 6-7 PbBufferOffsets ..................................... 6-10 PbCreatePhonebook ................................... 6-13 PbFindFirstOrNext ................................... 6-15 PbFreePBE ........................................... 6-18 PbGarbageCollect .................................... 6-20 PbGetEntry .......................................... 6-22 PbLookUpSendInfo .................................... 6-25 iv PbModifyEntry ....................................... 6-28 PbOpenPhonebook ..................................... 6-31 PbRemoveEntry ....................................... 6-33 PbRemoveFromGroup ................................... 6-36 A TOOLKIT COMPATIBILITY WITH TURBO C v ABOUT THIS MANUAL 1 This manual, which accompanies your diskette, describes the Programmer's Toolkit for CAS and the Phonebook. This chapter presents an overview of the manual's contents and describes the conventions used. How To Use This Manual This manual explains the features and operation of the Toolkit libraries. Once you are familiar with the libraries and how to use them, you can use this manual as a quick reference for function names, parameters, and return values. Chapter 1. About This Manual This chapter presents an overview of the manual's contents and describes the conventions used. Chapter 2. Getting Started This chapter introduces you to the Toolkit and discusses information that you will need to use the Toolkit. Read this chapter before you try to install the Toolkit. Chapter 3. Overview of CAS and the Toolkit This chapter discusses CAS and the Toolkit and explains the Toolkit components. This chapter, while valuable to all users, is directed to less experienced CAS developers. Chapter 4. CASLIB: C Library For CAS Developers This chapter describes the CASLIB library. This library contains the low-level functions that perform the services of the CAS 1.0B function set. Chapter 4 also describes how to compile and link with CASLIB. The last section describes each of the CASLIB functions in detail. Chapter 5. FAXLIB: High-Level Library For CAS Developers This chapter describes the FAXLIB library for CAS developers. The FAXLIB Library contains the high-level functions that provide simplified management of events and error handling. This chapter also describes how to compile and link with FAXLIB. The last section describes each of the FAXLIB functions in detail. About This Manual 1-1 1-1 About This Manual Chapter 6. PBLIB: Library for Phonebook Management This chapter describes the PBLIB library for phonebook management. The phonebook is a database that CAS applications might use to make task generation easier for end-users. This chapter also describes how to compile and link with PBLIB. The last section describes each of the PBLIB functions in detail. Appendix A. Toolkit Compatibility With Turbo C This appendix provides information on using Turbo C with the Toolkit. Conventions In this manual, the parameters and variables for each library are shown in italics. This manual also uses the following convention. NOTE: Indicates important information about how something works or how you should do something. 1-2 About This Manual GETTING STARTED 2 The Toolkit is a library of functions that provides C programmers with a convenient interface to both the DCA/Intel Communicating Applications Specification (CAS) Version 1.0B and the Phonebook. The Toolkit gives C developers an efficient way to build communications into their application programs. This chapter introduces you to the Toolkit and discusses the following topics: ╖ Toolkit Requirements ╖ What's on the Diskette ╖ Which Library to Use ╖ Installing the Toolkit ╖ Modifying the Libraries. For a discussion on the concepts and terminology that apply to CAS and the Toolkit, refer to Chapter 3. Toolkit Requirements The Toolkit system requirements are determined by the CAS- supported hardware (such as Intel's Connection CoProcessor) that you are using. To use the Toolkit libraries, you need the following software: ╖ DOS 3.0 or higher ╖ Microsoft C 5.1 or higher You can also use Borland's Turbo C. For information on using Turbo C with the Toolkit, see Appendix A. The Toolkit libraries use no graphic video modes, nor do they use a mouse. NOTE: Intel requires users of the Programmer's Toolkit for CAS and the Phonebook to have access to a copy of the DCA/Intel Communicating Applications Specification for additional information. Getting Started 2-1 2-1 Getting Started What's On The Diskette? The root directory of the Toolkit diskette has the following six directories: ╖ INCLUDE ╖ LIB ╖ CASSRC ╖ FAXSRC ╖ PBSRC ╖ MANUAL The INCLUDE directory contains all the include files (*.H and *.INC) that are used by the libraries and programs that use the libraries. These files are: ╖ CAS.H ╖ FAX.H ╖ FAXGLOB.H ╖ FAXDFLTS.H ╖ FAXERROR.H ╖ PHONEBK.H ╖ PBGLOBAL.H ╖ PBDFLT.H ╖ PBERROR.H ╖ MULTI.INC ╖ MODEL.INC The LIB directory contains four memory-model versions (SMALL, MEDIUM, COMPACT, and LARGE) for each of the three libraries of the Toolkit. The libraries were compiled and built by Microsoft C 5.1. The CASLIB files are: ╖ SCASLIB.LIB ╖ MCASLIB.LIB ╖ CCASLIB.LIB ╖ LCASLIB.LIB The FAXLIB files are: ╖ SFAXLIB.LIB ╖ MFAXLIB.LIB ╖ CFAXLIB.LIB ╖ LFAXLIB.LIB 2-2 Getting Started The PBLIB files are: ╖ SPBLIB.LIB ╖ MPBLIB.LIB ╖ CPBLIB.LIB ╖ LPBLIB.LIB The three SRC directories contain the source files for the functions in the three Toolkit libraries. They also contain sample make files and batch files for building the libraries using Microsoft C 5.1. The MANUAL directory contains two files: an ASCII version of this manual and an ASCII version of Recent News About the CAS and Phonebook Toolkit. ╖ TKMANUAL.TXT ╖ NEWS.TXT In addition to the six directories, the root directory contains the following two files: ╖ README ╖ WHATSOND.ISK Which Library To Use The Toolkit consists of three libraries of functions. These are as follows: CASLIB contains the low-level functions that perform the services of the CAS function set. FAXLIB contains the high-level functions that provide simplified management of communications tasks and error handling. PBLIB contains the phonebook functions which provide an interface to the Intel phonebooks. NOTE: The FAXLIB functions use some functions from CASLIB. If you use FAXLIB functions, your application must be linked to both the FAXLIB and CASLIB libraries. Because the CASLIB is a one-to-one mapping of C functions to the assembly-level CAS functions, C applications already written to the CAS functions can be made more compact and maintainable by converting CAS calls to CASLIB function calls. Getting Started 2-3 New CAS applications can benefit from using the CASLIB and FAXLIB functions in combination. A time performance gain results from using the CASLIB functions exclusively, but the FAXLIB functions require less application code. Refer to the following two code examples which submit the same Send event. The first example uses the low-level CASSubmitTask function. NOTE: For information on "Send events," refer to Chapter 3 of this manual. int event_hdl; FILE *fptr; ECF *ecf; FTR *ftr; ecf = (ECF *)calloc(1, sizeof(ECF)); ftr = (FTR *)calloc(1, sizeof(FTR)); ecf->FileCount = 1; ecf->FTROffset = 383; strcpy(ecf->DestinationName, "lab fax"); strcpy(ecf->Phone, "9, 645-8468"); strcpy(ftr->FileName, "c:\\autoexec.bat"); fptr = fopen("c:\\sample.ecf", "wb"); fwrite(ecf, sizeof(ECF), 1, fptr); fwrite(ftr, sizeof(FTR), 1, fptr); fclose(fptr); free(ecf); free(ftr); event_hdl = CASSubmitTask("c:\\sample.ecf"); The second example uses the high-level FAXSend function. FILELIST file1 = {"c:\\autoexec.bat", ASCII, NULL}; int retval; retval = FAXSend("lab fax", "9, 645-8468", &file1, &NULL, &NULL); 2-4 Getting Started The PBLIB functions manage the phonebook files; they do not perform any communications activity or interface with the Resident Manager or the fax board. While the Intel phonebook format is described in the DCA/Intel Communicating Applications Specification, it is not officially part of the specification. The Intel phonebook format is compatible with Intel's application software. It may or may not be compatible with phonebook formats used by other CAS compatible boards. PBLIB uses the Intel phonebook format described in the DCA/Intel Communicating Applications Specification. NOTE: Be advised that using PBLIB may result in creating phonebooks that are compatible only with Intel phonebooks. Installing The Toolkit To install the files needed to link an application to one or more of the Toolkit libraries, do the following: 1. Switch to your application subdirectory (for example, \APP\SOURCE) on the hard disk as follows: C>CD \APP\SOURCE 2. Copy the Include files: C>COPY A:\INCLUDE\*.* 3. Copy the libraries with the following command: C>COPY A:\LIB\*.* Refer to the appropriate chapter for each library for information on linking applications. For additional information on the structure of the Toolkit, refer to the README file in the root directory of the Intel diskette. Getting Started 2-5 Modifying The Libraries To modify and rebuild the FAXLIB and PBLIB libraries, you need Microsoft C version 5.1 or later. The CASLIB functions are C function versions of the CAS functions and are a public standard. You probably should not modify them. If you do modify these functions, you need Microsoft Macro Assembler version 5.1 or later. Make files, batch files, and READ.ME files with directions for building the three libraries are in the SRC directories of the CAS and Phonebook Toolkit diskette. 2-6 Getting Started The source files for the libraries are in the following subdirectories: ╖ For CASLIB: \CASSRC ╖ For FAXLIB: \FAXSRC ╖ For PBLIB: \PBSRC Getting Started 2-7 OVERVIEW OF CAS AND THE TOOLKIT 3 This chapter provides an overview of the DCA/Intel Communicating Applications Specification (CAS) Version 1.0B and the Toolkit. All users will profit from reading this chapter but it is directed specifically to new CAS developers. The information in this chapter provides you with a background in the basic components and terminology that apply to CAS and the Toolkit. For additional information on the components presented here, refer to the individual reference page for the appropriate function or refer to the DCA/Intel Communicating Applications Specification. This chapter discusses the following components of the Programmer's Toolkit for CAS and the Phonebook: ╖ Resident Manager ╖ Queues and Events ╖ Control Files ╖ File Transfer Records (FTRs) ╖ Event Handles ╖ Toolkit Data Structures ╖ Error Handling Resident Manager The Resident Manager is software that manages CAS events and takes care of CAS internal housekeeping. For example, the Resident Manager takes information to be sent from the application and sends it. When receiving information, the Resident Manager stores the information and makes it available to the application. The Resident Manager provides these services and, as a result, the developer does not have to monitor events. The following sections define CAS events and describe how the Resident Manager monitors them. Queues and Events The Resident Manager maintains the following three queues internally. Each queue consists of zero or more individual events. Overview of CAS and the Toolkit 3-1 3-1 Overview of CAS and the Toolkit Task Queue is a list of pending send events. A Send event occurs when a local computer transmits information to a remote computer or a fax machine. The application developer initiates a Send event. Receive Queue is a list of the received events. A Receive event occurs when the local computer receives information from a remote computer or a fax machine. An external activity, e.g., a remote computer call initiates a Receive event. Log Queue is a record of send and receive events. The local computer records the details of a successful or unsuccessful communication activity. The Resident Manager generates a Log automatically when a Send event or a Receive event occurs. Control Files and File Transfer Records (FTRs) A Control File contains the specific control information (who to call, when to call, etc.) for a given Send or Receive event. For example, the Control File for a Send event contains the phone number, date, and time information for that event. The File Transfer Record (FTR) is a data structure that is a component of the Control File. It contains specific information about the file to be sent (file name, file type, etc.). There is one FTR for each file sent. For example, if developers want to send two files to a remote computer, they need to complete one Control File and two FTR(s). The exact formats for both the Control File and the FTR can be found in the DCA/Intel Communicating Applications Specification. Control Files for Send Events While Send events are pending, the Resident Manager keeps the Control Files in the Task Queue. Once a Send event is completed, successfully or not, the Resident Manager keeps the Control File in Log Queue. Current Events When the hardware is sending or receiving an event, that event is current. Applications can access information on a current event only by using the function CASGetCurrentEventStatus. 3-2 Overview of CAS and the Toolkit Control Files for Receive Events While Receive events are being received, they are current events. Once a Receive event is completed, the Resident Manager creates and places a Control File for it in both the Receive and the Log queues. The Control File in the Log Queue is a copy of the Control File in the Receive Queue. Event Handles Each event is associated with a unique, non-zero positive integer called an event handle. All the Toolkit functions that submit events return this handle if they are successful. The Toolkit functions that find events use this number as their search key. This number stays the same when the event changes queues, between invocations of the application, even when the computer is turned off and on again. Toolkit Data Structures and Error Handling The following sections briefly discuss the Toolkit design. For additional information, read the DCA/Intel Communicating Applications Specification or the commented include files that are provided with the Toolkit. The Include Files The include files provided with the Toolkit are: CAS.H defines CAS data types, constants, structures, and function prototypes for CASLIB functions. Include this file for applications that use the CASLIB or FAXLIB functions. FAX.H defines structures, constants, and function prototypes for FAXLIB functions. Include this file for applications that use the FAXLIB functions. FAXGLOB.H defines the global error number variables FAXerrno and CASerrorcode. Include this file for applications that use FAXLIB functions. FAXDFLTS.H defines and initializes default FTR and Event Control structures. Include this file for applications that use either FAXSend or FAXSubmitTask. Overview of CAS and the Toolkit 3-3 FAXERROR.H defines and initializes the global error message tables FAXerrlist and CASerrors. Include this file for applications that use FAXError. PHONEBK.H defines data types, constants, structures, and function prototypes for functions in PBLIB. Include this file for applications that use the PBLIB functions. PBGLOBAL.H defines the global error number variable Pberrno. Included this file for applications that use the PBLIB functions. PBDFLT.H defines and initializes the default phonebook header structure used by the PBLIB function PbCreatePhonebook. Include this file for applications that use PbCreatePhonebook. PBERROR.H defines and initializes the global message table, Pberrlist. Include this file for applications that use this table. CAS Structures The contents of Control Files and other data structures used by the Resident Manager are specified in the DCA/Intel Communicating Applications Specification by bit field. To make programming to CAS easier for application developers using high-level languages like C, Intel has developed structures in the Toolkit that follow those bit-field specifications. The Toolkit structures are: Toolkit Structure Name CAS Name ECF Control File. FTR File Transfer Record. EDB External Data Block, defined under CASGetExternalData. SFTR The data area defined under the CASSubmitSingleFile. CECS The subset of the Task Control File defined under CASGetCurrentEventStatus. HWSTAT Hardware status data, returned by CASGetHardwareStatus. PCXFILE Header of a PCX graphic file. 3-4 Overview of CAS and the Toolkit DCXFILE Header of a DCX graphic file. QSTAT Queue status returned by CASGetQueueStatus. CAS_DATE Year, month, and day, used by CASGetEventDate and CASSetTaskDate to get and set an event's date. CAS_TIME Hour, minute, and second, used by CASGetEventTime and CASSetTaskTime, to get and set an event's time. Overview of CAS and the Toolkit 3-5 Additional Structures Besides the structures that are defined in CAS, the Toolkit uses additional structures for managing the fax and file transfer events. ErrorTable For mapping CAS error codes to message strings and error classes. FTRLIST Linked list of FTRs. FILELIST Linked list of filenames and file types. ECS Event Control Structure. Includes the Control File, the cover text, and the FTRLIST. Error Handling The CASLIB functions return negative CAS error codes as described in the DCA/Intel Communicating Applications Specification. The FAXLIB functions provide additional error handling support through two global error variables and two error message tables. The global error variables are FAXerrno and CASerrorcode defined in the file FAXGLOB.H. The error message tables are FAXerrlist and CASerrors, defined in the file FAXERROR.H. When FAXLIB functions encounter error conditions or warnings, they set the global variable FAXerrno to a positive non-zero value. If FAXerrno is set to a positive value, it indexes the message table FAXerrlist. To retrieve error and warning information from FAXLIB function calls, applications must include the file FAXERROR.H, test FAXerrno after each call, and if it's non-zero, look up the message in FAXerrlist. The FAXLIB function FAXError uses these global variables and message tables to find and return error messages to applications using either FAXLIB or CASLIB functions. For information on how to use FAXError, refer to the reference page for that function. All the FAXLIB functions return 0 (NULL or FAIL) to indicate an error, so testing both FAXerrno and the return value determines whether an error or warning has occurred. 3-6 Overview of CAS and the Toolkit When PBLIB functions encounter error conditions, they set the global variable Pberrno to a positive non-zero value. Applications that want to use Pberrno to obtain information about errors should include the file PBERROR.H and use Pberrno as an index to the table of error messages in PBerrlist. If the applications succeed without error or warning, they set Pberrno to zero. All PBLIB functions except PbFreePBE return 0 (NULL or FAIL) to indicate an error, so testing both Pberrno and the return value determines whether an error or warning has occurred. Memory Allocation The FAXLIB and PBLIB functions provide two ways to handle memory allocation. Either the application provides all the memory for the data structures or the function allocates the memory, using the malloc C Library function. Applications can choose to manage memory or let the Toolkit manage memory. This flexibility allows applications to use expanded memory if it is available. When a function returns a substantial or potentially substantial amount of data, it takes as one of its parameters a pointer to a structure to hold that data. The return value is also a pointer to the data returned. If the application provides all the memory itself, it passes a valid pointer to the memory space. The function uses the memory space for the data returned and returns the same pointer. If the application has the Toolkit function allocate the memory, the application passes NULL as that pointer parameter. Then the Toolkit function allocates the memory it needs, fills that memory with the data, and returns the pointer to the memory allocated. Overview of CAS and the Toolkit 3-7 CASLIB: C LIBRARY 4 FOR CAS DEVELOPERS The CASLIB functions provide a one-to-one mapping of C language functions to the assembly-level functions defined in CAS 1.0B. To provide greater efficiency and a broader base of compatible compilers, all CASLIB functions use the Pascal calling convention. CAS data structures are provided in the form of C structures and are defined in the file CAS.H. This chapter describes each function listed in alphabetical order. The format of the function descriptions is as follows: ╖ Description of the function. ╖ Summary provides the syntax for each function. ╖ Parameters describes the parameters for each function. ╖ Return Value can be used to test for error conditions or to provide the requested information. ╖ Remarks provides additional information on the function. ╖ See Also lists related functions. ╖ Example Program shows how the function is used. Compiling and Linking With CASLIB To use functions from the CASLIB library, applications must include the file CAS.H and link to the correct library for the memory model they are using. For example, the following commands are the compile and link commands for an application called SAMPLE.C written for the small memory model. cl /c /AS sample.c link sample ,, NUL, SCASLIB; To use CL.EXE to both compile and link, type the following command: cl /AS sample.c /l SCASLIB CASLIB: C Library for CAS Developers 4-1 4-1 CASLIB: C Library for CAS Developers CASLIB Functions Grouped by Operation The CASLIB functions can be divided into five groups: ╖ Configuration ╖ Event and Queue Queries ╖ Event Creation ╖ Event Manipulation ╖ File Management Configuration These functions get information about whether the Resident Manager is installed, the status and condition of the hardware, and the current setup configuration. CASAutoReceiveState Determines or sets the current state of the auto-receive feature. CASGetExternalData Gets the External Data Block (EDB) in an EDB structure. CASGetHardwareStatus Gets hardware-specific status information. CASGetInstalledState Determines whether the Resident Manager is installed. CASRunDiagnostics Runs a set of diagnostics or reports on their progress. CASUnloadResidentManager Removes the Resident Manager from memory. Event and Queue Queries These functions get information about events in the Task and Receive queues and the Log. CASFindFirst Finds the earliest or latest event in the chosen queue that matches the given status and chronological direction. CASFindNext Finds the next event in the queue according to the settings of the last call to CASFindFirst. CASGetCurrentEventStatus Gets information about the currently executing event. CASGetEventDate Gets the date an event is scheduled to occur. CASGetEventTime Gets the time an event is scheduled to occur. CASGetQueueStatus Gets status information about the specified queue. Event Creation These functions submit events to be sent to the Resident Manager. These events are defined either in Control Files or data structures in memory. These functions do not create those Control Files or initialize those structures. 4-2 CASLIB: C Library for CAS Developers CASSubmitSingleFile Submits a Send event specified in a data structure to the Resident Manager. CASSubmitTask Submits the event specified in a Control File to the Resident Manager. Event Manipulation These functions manipulate events either by rescheduling events or by aborting the current event. CASAbortCurrentEvent Aborts the currently executing event. CASSetTaskDate Changes the event's scheduled execution date in the Control File. CASSetTaskTime Changes the event's scheduled execution time in the Control File. File Management These functions provide access to files associated with events. They access the Control File for the event, or, in the case of Receive events, they access either the Control File or one of the files received. CASDeleteAllFiles Deletes all the files associated with all the events in the specified queue. CASDeleteFile Deletes a file associated with the specified event. CASMoveReceivedFile Moves and renames a received file to the specified directory and filename. CASOpenFile Opens a file associated with the specified event. CASLIB: C Library for CAS Developers 4-3 02H CASAbortCurrentEvent Description Aborts the currently executing event. Aborting the event is not instantaneous. It can take up to 30 seconds. Summary #include <cas.h> int PASCAL CASAbortCurrentEvent (void); Input Parameter None. Output Parameter None. Return Value Returns the event handle of the aborted event if successful; otherwise, returns a negative CAS error code. See Also CASDeleteFile (08H) Example Program The following program aborts the currently executing event, if there is one. #include <stdio.h> #include <cas.h> main () { int retval; retval = CASAbortCurrentEvent(); if (retval > 0) { printf("Event 0X%X has been aborted\n", retval); } 4-4 CASLIB: C Library for CAS Developers 02H CASAbortCurrentEvent else { printf("AbortCurrentEvent error code is: %X", -retval); } } CASLIB: C Library for CAS Developers 4-5 0FH CASAutoReceiveState Description Determines or sets the current state of the auto-receive feature. If an event is in progress, the new auto-receive state does not take effect until the event is completed. Summary #include <cas.h> int PASCAL CASAutoReceiveState (mode, rings); Input Parameter BYTE mode; GET to get the current auto-receive state. SET to set the auto-receive state. If mode is GET, rings returns the number of rings currently set. If mode is SET, the number of rings is set to rings. Output Parameter BYTE *rings; Pointer to the number of rings before answer or 0 to disable if mode is SET. If the result is AR_ON, rings contains the number of rings before the hardware answers. Return Value Returns AR_ON or AR_OFF to indicate the auto-receive state if successful; otherwise, returns a negative CAS error code. Example Program The following program determines whether auto-answer is on or off, and if on, how many rings the hardware is set to before it answers. #include <stdio.h> #include <cas.h> main () { int retval; BYTE rings; 4-6 CASLIB: C Library for CAS Developers 0FH CASAutoReceiveState retval = CASAutoReceiveState(GET, &rings); if (!(retval < 0)) { switch (retval) { case AR_ON: printf ("RM will answer at %d rings\n", rings); break; case AR_OFF: printf("RM AutoReceive is OFF\n"); } } } CASLIB: C Library for CAS Developers 4-7 09H CASDeleteAllFiles Description Deletes all the files associated with all the events in the specific queue. Summary #include <cas.h> int PASCAL CASDeleteAllFiles (queue); Input Parameter BYTE queue; TASK_QUEUE, RECEIVE_QUEUE, or LOG_QUEUE. Output Parameter None. Return Value Returns 0 if successful; otherwise, returns a negative CAS error code. Remarks Whenever CASDeleteAllFiles deletes all received files of an event, the Resident Manager sets the FileStatus field in the received files' FTR in the Log Control File for that event. This function deletes all Task Control files, all Received Control files and the associated received files, or all Log Control files. See Also CASAbortCurrentEvent (02H), CASDeleteFile (08H) 4-8 CASLIB: C Library for CAS Developers 09H CASDeleteAllFiles Example Program The following program deletes all events scheduled to execute. #include <stdio.h> #include <cas.h> main () { int retval; retval = CASDeleteAllFiles(TASK_QUEUE); if (!retval) { printf("All pending events cancelled\n"); } } CASLIB: C Library for CAS Developers 4-9 08H CASDeleteFile Description Deletes the indicated file associated with the specified event. Summary #include <cas.h> int PASCAL CASDeleteFile (handle, file, queue); Input Parameters int handle; Event handle associated with the file to delete. int file; For events in the Receive Queue, either 0 for the Receive Control File and all that event's received files, or the received file's number to be deleted. This number applies only to events in the Receive Queue and is ignored for events in the Task Queue and the Log. The number is interpreted as follows: 0 - Delete all files associated with the specified Receive Control File (including the Receive Control File). 1 - Delete the first received file associated with the event handle. 2 - Delete the second received file associated with the event handle. n - Delete the nth received file associated with the event handle. BYTE queue; TASK_QUEUE, RECEIVE_QUEUE, or LOG_QUEUE. Output Parameter None. Return Value Returns 0 if successful; otherwise, returns a negative CAS error code. Remarks Whenever CASDeleteFile deletes a received file, the Resident Manager sets the FileStatus field in the received file's FTR in both the Receive Control File and the Log Control File. See Also CASAbortCurrentEvent (02H), CASDeleteAllFiles (09H) Example Program The following program finds the first event in the Log Queue and deletes its Control File. #include <stdio.h> #include <cas.h> 4-10 CASLIB: C Library for CAS Developers 08H CASDeleteFile main () { int retval, event_hdl; event_hdl = CASFindFirst(ANY_STATUS, SEARCH_FORWARD, LOG_QUEUE); if (event_hdl == -NO_MORE_EVENTS) { printf("No logged events\n"); } else { retval = CASDeleteFile(event_hdl, 0, LOG_QUEUE); if (!retval) { printf("1st logged event file deleted\n"); } } } CASLIB: C Library for CAS Developers 4-11 05H CASFindFirst Description Finds the earliest or latest event in the chosen queue that matches the given status and chronological direction. Summary #include <cas.h> int PASCAL CASFindFirst (status, direction, queue); Input Parameters int status; ANY_STATUS, COMPLETED, WAITING, DIALED, SENDING, RECEIVING, ABORTED, or negative CAS error code. BYTE direction; SEARCH_FORWARD (chronologically from the first occurring event to the last occurring event) or SEARCH_BACKWARD (chronologically from the last occurring event to the first occurring event). BYTE queue; TASK_QUEUE, RECEIVE_QUEUE or LOG_QUEUE. Output Parameter None. Return Value Returns the event handle of the event found if successful; otherwise, returns a negative CAS error code. NOTE: If there are no events in the chosen queue that match the given status, a negative CAS error code is returned. The negative (2's complement) of this error code is 0204H, NO_MORE_EVENTS. See Also CASFindNext (06H), CASOpenFile (07H) 4-12 CASLIB: C Library for CAS Developers 05H CASFindFirst Example Program The following program finds the event in the Task Queue that is scheduled to execute the earliest. #include <stdio.h> #include <cas.h> main () { int retval; retval = CASFindFirst(ANY_STATUS, SEARCH_FORWARD, TASK_QUEUE); if (retval == -NO_MORE_EVENTS) { printf("No events in Task Queue\n"); } else if (retval > 0) { printf("First pending event is # 0X%X\n", retval); } } CASLIB: C Library for CAS Developers 4-13 06H CASFindNext Description Finds the next event in the queue according to the settings of the last call to CASFindFirst. Each subsequent call to the CASFindNext function returns the event handle of the next event using the same direction and status parameters set by the CASFindFirst function in the specified queue. Summary #include <cas.h> int PASCAL CASFindNext (queue); Input Parameter BYTE queue; TASK_QUEUE, RECEIVE_QUEUE, or LOG_QUEUE. Output Parameter None. Return Value Returns the event handle of the event found if successful; otherwise, returns a negative CAS error code. NOTE: If there are no events in the chosen queue that match the given status, a negative CAS error code is returned. The negative (2's complement) of this error code is 0204H, NO_MORE_EVENTS. See Also CASFindFirst (05H), CASOpenFile (07H) 4-14 CASLIB: C Library for CAS Developers 06H CASFindNext Example Program The following program finds all the events in the Log Queue. #include <stdio.h> #include <cas.h> main () { int retval; retval = CASFindFirst (ANY_STATUS, SEARCH_FORWARD, LOG_QUEUE); if (retval == -NO_MORE_EVENTS) { printf("No events in Log Queue\n"); } else if (retval > 0) { printf("First logged event is 0X%X\n", retval); } while (retval != -NO_MORE_EVENTS) { retval = CASFindNext(LOG_QUEUE); if (retval > 0) { printf("Next logged event is 0X%X\n", retval); } } } CASLIB: C Library for CAS Developers 4-15 10H CASGetCurrentEventStatus Description Gets information about the currently executing event. Summary #include <cas.h> int PASCAL CASGetCurrentEventStatus (buffer); Input Parameter None. Output Parameter CECS *buffer; Pointer to a valid Current Event Control Structure (CECS). If the call is successful, the CECS structure is filled in with information about the current event. See the Get Current Event Status function (10H) in the DCA/Intel Communicating Applications Specification for information on the CECS structure. Return Value Returns the event handle of the current event if successful; otherwise, returns a negative CAS error code. Example Program The following program gets information about the status of the currently executing event, if there is one. #include <stdio.h> #include <cas.h> main () { int retval; CECS event; 4-16 CASLIB: C Library for CAS Developers 10H CASGetCurrentEventStatus retval = CASGetCurrentEventStatus(&event); if (retval > 0) { printf("Event currently executing, 0X%x,\n", retval); printf(" is sending file %s to %s\n", event.CurrentFileInTransit.FileName, event.ControlFile.DestinationName); } else { printf("No event currently executing\n"); } } CASLIB: C Library for CAS Developers 4-17 0AH CASGetEventDate Description Gets the date an event is scheduled to occur. Summary #include <cas.h> int PASCAL CASGetEventDate (handle, queue, date); Input Parameters int handle; Event handle of the event to query. BYTE queue; TASK_QUEUE, RECEIVE_QUEUE, or LOG_QUEUE. Output Parameter CAS_DATE *date; Pointer to a CAS_DATE structure. If successful, the CAS_DATE structure is filled in with information from the specified event. Return Value Returns 0 if successful; otherwise, returns a negative CAS error code. See Also CASSetTaskDate (0BH), CASGetEventTime (0CH) Example Program The following program gets the date of the oldest Receive event in the Receive Queue. #include <stdio.h> #include <cas.h> main () { int event_hdl, retval; CAS_DATE date; event_hdl = CASFindFirst(ANY_STATUS, SEARCH_FORWARD, RECEIVE_QUEUE); 4-18 CASLIB: C Library for CAS Developers 0AH CASGetEventDate if (event_hdl > 0) { retval = CASGetEventDate(event_hdl, RECEIVE_QUEUE, &date); if (!retval) { printf ("Event was received on %d/%d/%d\n", date.Month, date.Day, date.Year); } } } CASLIB: C Library for CAS Developers 4-19 0CH CASGetEventTime Description Gets the time an event is scheduled to occur. Summary #include <cas.h> int PASCAL CASGetEventTime (handle, queue, time); Input Parameters int handle; Event handle of the event to query. BYTE queue; TASK_QUEUE, RECEIVE_QUEUE, or LOG_QUEUE. Output Parameter CAS_TIME *time; Pointer to a CAS_TIME structure. If successful, the CAS_TIME structure is filled in with information for the specified event. Return Value Returns 0 if successful; otherwise, returns a negative CAS error code. See Also CASGetEventDate (0AH), CASSetTaskTime (0DH) Example Program The following program gets the execute time of the first event in the Receive Queue. #include <stdio.h> #include <cas.h> main () { int event_hdl, retval; CAS_TIME time; event_hdl = CASFindFirst(ANY_STATUS, SEARCH_FORWARD, RECEIVE_QUEUE); if (event_hdl > 0) { retval = CASGetEventTime(event_hdl, RECEIVE_QUEUE, &time); if (!retval) { printf("Event was received at %d:%d:%d\n", time.Hour, time.Minute, time.Second); } } } 4-20 CASLIB: C Library for CAS Developers 0EH CASGetExternalData Description Returns the External Data Block (EDB) in an EDB structure. Summary #include <cas.h> int PASCAL CASGetExternalData (buffer); Input Parameter None. Output Parameter EDB *buffer; Pointer to a valid EDB structure. See the Get External Data Block function (0EH) in the DCA/Intel Communicating Applications Specification for additional information on the EDB structure. If successful, the EDB structure is filled with the EDB information. Return Value Returns 0 if successful; otherwise, returns a negative CAS error code. Example Program The following program accesses the EDB to determine the version numbers of the Resident Manager. #include <stdio.h> #include <cas.h> main () { int retval; EDB edb; retval = CASGetExternalData(&edb); if (!retval) { printf("Installed Resident Manager version is: %d.%d\n", (int)edb.CASMajorVer, (int)edb.CASMinorVer); } } CASLIB: C Library for CAS Developers 4-21 12H CASGetHardwareStatus Description Returns the hardware-specific status information of the communications hardware in a HWSTAT structure. For information on the content and format of the hardware status structure for the Intel Connection CoProcessor, refer to the Hardware-Specific Information for Intel Communications Products Supporting the DCA/Intel Communicating Applications Specification provided with the Toolkit. Summary #include <cas.h> int PASCAL CASGetHardwareStatus (buffer); Input Parameter None. Output Parameter HWSTAT *buffer; Pointer to a 128-byte area in which hardware status information is returned. Return Value Returns 0 if successful, otherwise, returns a negative CAS error. See Also CASGetTaskStatus (10H), CASGetQueueStatus (11H) Example Program The following program gets and displays (in hexadecimal) all the bytes in the hardware-specific status information structure. #include <stdio.h> #include <cas.h> main () { int retval, i; BYTE val; HWSTAT status; 4-22 CASLIB: C Library for CAS Developers 12H CASGetHardwareStatus retval = CASGetHardwareStatus(&status); if (!(retval)) { printf("HW status info, as hex bytes:\n"); for (i=0; i<sizeof(HWSTAT); i++) { printf(" %02X", val = ((char *)&status)[i]); } printf("\n"); } else { printf("GetHardwareStatus error code is: %X\n", -retval); } } CASLIB: C Library for CAS Developers 4-23 00H CASGetInstalledState Description Determines whether the Resident Manager is currently installed, and if not, whether it can be installed. Summary #include <cas.h> int PASCAL CASGetInstalledState (void); Input Parameter None. Output Parameter None. Return Value Returns one of the following constants: INSTALLED if Resident Manager is installed. NOTiOK if Resident Manager is NOT installed but can be installed. NOTiNO if Resident Manager is NOT installed and can't be installed. See Also CASGetExternalData (0EH) 4-24 CASLIB: C Library for CAS Developers 00H CASGetInstalledState Example Program The following program determines whether the Resident Manager is installed. #include <stdio.h> #include <cas.h> main () { int retval; retval = CASGetInstalledState(); if (retval == INSTALLED) { printf("Resident Manager is installed\n"); } else { printf("Resident Manager is not installed\n"); } } CASLIB: C Library for CAS Developers 4-25 11H CASGetQueueStatus Description Gets status information about the specified queue in a QSTAT structure. The QSTAT fields are described in the comments to the QSTAT definition in the file CAS.H. Summary #include <cas.h> int PASCAL CASGetQueueStatus (queue, buffer); Input Parameter BYTE queue; The queue to check (TASK_QUEUE, RECEIVE_QUEUE, or LOG_QUEUE). Output Parameter QSTAT *buffer; Pointer to a QSTAT structure. If successful, the QSTAT buffer is filled with the current status of the specified queue. Return Value Returns 0 if successful; otherwise, returns a negative CAS error code. Remarks This function returns the following: the total number of changes made to the queue since the Resident Manager was started, the current number of Control Files in the queue, and the current number of received files. Example Program The following program gets status information about the Log Queue. #include <stdio.h> #include <cas.h> main () { int retval; QSTAT buffer; retval = CASGetQueueStatus(LOG_QUEUE, &buffer); if (!retval) { printf("Log Queue status:\n"); printf(" Number of logged events: %d\n", buffer.QControlFiles); printf(" Changes since last installed: %d\n", buffer.QChanges); } else { printf("GetQueueStatus failed,\n"); printf("CAS error code is 0X%X\n", -retval); } 4-26 CASLIB: C Library for CAS Developers 11H CASGetQueueStatus } CASLIB: C Library for CAS Developers 4-27 14H CASMoveReceivedFile Description Moves and renames a received file to the directory and filename specified in *filespec. Summary #include <cas.h> int PASCAL CASMoveReceivedFile (handle, file, filespec); Input Parameters int handle; Event handle of the Receive event. int file; The received file to move. Must be non-zero to specify a received file. The number is interpreted as follows: 1 - First received file 2 - Second received file 3 - Third received file n - nth received file. char *filespec; Pointer to a fully qualified NULL terminated string specifying the new path and filename. Output Parameter None. Return Value Returns 0 if successful; otherwise, returns a negative CAS error code. Remarks The path in *filespec must already exist. The file named by *filespec must not already exist or an error results. This function does not create directories. The *filespec can specify any disk drive physically in the system. Whenever CASMoveReceivedFile moves a received file, the Resident Manager sets the FileStatus field in the received file's FTR in both the Receive Control File and the Log Control File. 4-28 CASLIB: C Library for CAS Developers 14H CASMoveReceivedFile Example Program The following program moves the first received file of the oldest Receive event to drive C: under the name "\received.1". #include <stdio.h> #include <cas.h> main () { int event_hdl, retval; char *fname = "c:\\received.1"; event_hdl = CASFindFirst(ANY_STATUS, SEARCH_FORWARD, RECEIVE_QUEUE); if (event_hdl > 0) { retval = CASMoveReceivedFile(event_hdl, 1, fname); if (!retval) { printf("First received file saved as %s\n", fname); } else { printf("MoveReceivedFile failed,\n"); printf("CAS error code is: 0X%X", -retval); } } else { printf("Error occurred in CASFindFirst"); } } CASLIB: C Library for CAS Developers 4-29 07H CASOpenFile Description Opens a file associated with the specified event. Summary #include <cas.h> int PASCAL CASOpenFile (handle, file, queue); Input Parameters int handle; Event handle associated with the file to open. int file; For events in the Receive Queue, either 0 for the Receive Control File or the number of the received file. This number is interpreted as follows: 0 - The Received Control File 1 - First received file 2 - Second received file 3 - Third received file n - nth received file. For events in the Task Queue and the Log, this function opens the Control File for the event. BYTE queue; TASK_QUEUE, RECEIVE_QUEUE, or LOG_QUEUE. Output Parameter None. Return Value Returns the DOS file handle of the opened file if successful; otherwise, returns a negative CAS error code. Remarks After you obtain an event handle (either by scanning a queue using the CASFindFirst and CASFindNext functions or by creating an event using the CASSubmitTask function), you can use the CASOpenFile function to access the DOS file corresponding to the event. CASOpenFile opens the Control File for events in the Task Queue or the Log. This function opens the desired file in read-only mode and returns a DOS file handle. Whenever CASOpenFile opens a received file, the Resident Manager sets the FileStatus field in the received file's FTR in both the Receive Control File and the Log Control File. See Also CASSubmitTask (01H), CASFindFirst (05H), CASFindNext (06H), CASMoveReceivedFile (14H) 4-30 CASLIB: C Library for CAS Developers 07H CASOpenFile Example Program The following program finds the oldest Receive event in the Receive Queue and opens its Control File. #include <stdio.h> #include <cas.h> main () { int event_hdl, file_hdl; event_hdl = CASFindFirst(ANY_STATUS, SEARCH_FORWARD, RECEIVE_QUEUE); if (event_hdl == -NO_MORE_EVENTS) { printf("No received events\n"); } else { file_hdl = CASOpenFile(event_hdl, 0, RECEIVE_QUEUE); if (file_hdl > 0) { printf("Handle for event file: %d\n", file_hdl); } } } CASLIB: C Library for CAS Developers 4-31 13H CASRunDiagnostics Description Runs a set of diagnostics or reports on their progress. Summary #include <cas.h> int PASCAL CASRunDiagnostics (mode); Input Parameter BYTE mode; Determines which diagnostics function to invoke. Setting mode to a value of START starts the hardware diagnostics. Setting mode to a value of STATUS returns the status of the diagnostics. Output Parameter None. Return Value Depending on the action specified by mode, this function returns the following results: ╖ START returns 0 if successful (diagnostic begun); otherwise, returns a negative CAS error code. ╖ STATUS returns 40H if the diagnostics are in progress. It returns a positive value (other than 40H) if the diagnostics are completed successfully. It returns a negative value if the diagnostics failed. For information on the values, content, and format of the hardware status structure, refer to the Hardware-Specific Information for Intel Communications Products Supporting the DCA/Intel Communicating Applications Specification provided with the Toolkit. Example Program The following program starts and runs to completion the CAS diagnostics. #include <stdio.h> #include <cas.h> main () { int retval; retval = CASRunDiagnostics(START); if (!retval) { printf("Diagnostics started...\n"); do { retval = CASRunDiagnostics(STATUS); } while (retval == 0x40); if (retval >= 0) { printf("Diagnostics successful\n"); 4-32 CASLIB: C Library for CAS Developers 13H CASRunDiagnostics } else { printf("Diagnostics failed\n"); printf(" Failure code is 0X%X", retval); } } else { printf("Diagnostics failed to start,\n"); printf(" Failure code is 0X%X", retval); } } CASLIB: C Library for CAS Developers 4-33 0BH CASSetTaskDate Description Changes the event's scheduled execution date in the Control File. This function works only with events in the Task Queue. Summary #include <cas.h> int PASCAL CASSetTaskDate (handle, date); Input Parameters int handle; Event handle of the event to modify. CAS_DATE *date; Pointer to a valid, filled-in CAS_DATE structure. Output Parameter None. Return Value Returns 0 if successful; otherwise, returns a negative CAS error code. NOTE: Setting the date earlier than the current date causes the event to execute immediately. See Also CASGetEventDate (0AH), CASSetTaskTime (0DH) Example Program The following program changes the execution date of the earliest scheduled Send event in the Task Queue to 1/1/91. #include <stdio.h> #include <cas.h> main () { int event_hdl, retval; CAS_DATE date; event_hdl = CASFindFirst(ANY_STATUS, SEARCH_FORWARD, TASK_QUEUE); if (event_hdl > 0) { date.Year = 1991; date.Month = 1; date.Day = 1; retval = CASSetTaskDate(event_hdl, &date); if (!retval) { printf("Event date reset to %d/%d/%d\n", 4-34 CASLIB: C Library for CAS Developers 0BH CASSetTaskDate date.Month, date.Day, date.Year); } else { printf("SetTaskDate failed,\n"); printf("CAS error code is: 0X%X", -retval); } } } CASLIB: C Library for CAS Developers 4-35 0DH CASSetTaskTime Description Changes the event's scheduled execution time in the Control File. This function works only with events in the Task Queue. Summary #include <cas.h> int PASCAL CASSetTaskTime (handle, time); Input Parameters int handle; Event handle of the event to modify. CAS_TIME *time; Pointer to a valid, filled in CAS_TIME structure. Output Parameter None. Return Value Returns 0 if successful; otherwise, returns a negative CAS error code. NOTE: Setting the time earlier than the current time will cause the event to execute immediately if the date is set to the current date. Therefore, Intel recommends that you change the date before you change the time or you may accidentally send an event before you intend to. See Also CASSetTaskDate (0BH), CASGetEventTime (0CH) Example Program The following program sets the execute time of the earliest scheduled Send event in the Task Queue to 8:30 a.m. #include <stdio.h> #include <cas.h> main () { int event_hdl, retval; CAS_TIME time; event_hdl = CASFindFirst(ANY_STATUS, SEARCH_FORWARD, TASK_QUEUE); if (event_hdl > 0) { time.Hour = 8; time.Minute = 30; time.Second = 0; 4-36 CASLIB: C Library for CAS Developers 0DH CASSetTaskTime retval = CASSetTaskTime(event_hdl, &time); if (!retval) { printf("Event time reset to %d:%d:%d\n", time.Hour, time.Minute, time.Second); } else { printf("SetTaskTime failed,\n"); printf("CAS error code is 0X%X", -retval); } } } CASLIB: C Library for CAS Developers 4-37 15H CASSubmitSingleFile Description Submits a Send event specified in a data structure to the Resident Manager. NOTE: To send more than one file, use the CASSubmitTask function. Summary #include <cas.h> int PASCAL CASSubmitSingleFile (buffer); Input Parameter SFTR *buffer; Pointer to a data structure containing an abbreviated version of the information in the Task Control File. See the Submit a Single File to Send function in the DCA/Intel Communicating Applications Specification for more information on the SFTR structure. Output Parameter None. Return Value Returns the event handle if successful; otherwise, returns a negative CAS error code. Remarks The following fields of Control Files and FTRs are not present in the SFTR structure: Sender Name, Logo Filename CASSubmitSingleFile obtains these from the EDB. Page Length in Inches, Page Increments If the transmission is a fax, CASSubmitSingleFile uses the standard 11" page length. See Also CASSubmitTask (01H) 4-38 CASLIB: C Library for CAS Developers 15H CASSubmitSingleFile Example Program The following program creates a SFTR structure for a fax send and submits it to the Resident Manager. #include <stdio.h> #include <malloc.h> #include <string.h> #include <cas.h> main () { int event_hdl; SFTR *sftr; sftr = (SFTR *)calloc(1, sizeof(SFTR)); strcpy(sftr->DestinationName, "lab fax"); strcpy(sftr->FileName, "c:\\autoexec.bat"); strcpy(sftr->Phone, "9, 645-8468"); event_hdl = CASSubmitSingleFile(sftr); if (event_hdl > 0) { printf("Fax send successfully submitted\n"); } } CASLIB: C Library for CAS Developers 4-39 01H CASSubmitTask Description Submits the event specified in a Control File to the Resident Manager. Before invoking this function, prepare a Control File. Summary #include <cas.h> int PASCAL CASSubmitTask (filespec); Input Parameter char *filespec; Pointer to a complete path and filename of a Control File. Output Parameter None. Return Value Returns a positive event handle if successful; otherwise, returns a negative CAS error code. Remarks CASSubmitTask adds this Control File to the Task Queue if the event is to be sent in the future. Otherwise, the Resident Manager sends the event immediately. See Also CASSubmitSingleFile (15H) Example Program The following program creates a Control File for a Send event and submits it to the Resident Manager. #include <stdio.h> #include <malloc.h> #include <string.h> #include <cas.h> main () { int event_hdl; FILE *fptr; ECF *ecf; FTR *ftr; /* Allocate and clear Control File structures */ ecf = (ECF *)calloc(1, sizeof(ECF)); ftr = (FTR *)calloc(1, sizeof(FTR)); /* Set specific fields for this send */ ecf->FileCount = 1; 4-40 CASLIB: C Library for CAS Developers 01H CASSubmitTask ecf->FTROffset = 383; /* for no cover text */ strcpy(ecf->DestinationName, "lab fax"); strcpy(ecf->Phone, "9, 645-8468"); strcpy(ftr->FileName, "c:\\autoexec.bat"); /* Create the Control File and write structures to it */ fptr = fopen("c:\\sample.ecf", "wb"); fwrite(ecf, sizeof(ECF), 1, fptr); fwrite(ftr, sizeof(FTR), 1, fptr); fclose(fptr); /* Submit the task */ event_hdl = CASSubmitTask("c:\\sample.ecf"); if (event_hdl > 0) { printf("File %s is on it's way!\n", "c:\\autoexec.bat"); } else { printf("CASSubmitTask error is: 0X%x\n", -event_hdl); } free(ecf); free(ftr); } CASLIB: C Library for CAS Developers 4-41 16H CASUnloadResidentManager Description Removes the Resident Manager from memory. This function can be used to remove the Resident Manager as long as a Terminate and Stay Resident (TSR) has been loaded above the Resident Manager, there is a polled send present, or the Resident Manager or the hardware is busy. Summary #include <cas.h> int PASCAL CASUnloadResidentManager(void); Input Parameter None. Output Parameter None. Return Value Returns 0 if successful; otherwise, returns a negative CAS error code. Remarks Removing the Resident Manager from memory suspends all pending events. For example, if an event is scheduled to be sent in 5 minutes, it will not be sent until the Resident Manager is reloaded. After the Resident Manager is reloaded, it will immediately send late events in the assigned order. Example Program The following program removes the Resident Manager from memory. #include <stdio.h> #include <cas.h> main () { int retval; 4-42 CASLIB: C Library for CAS Developers 16H CASUnloadResidentManager retval = CASUnloadResidentManager(); if (!retval) { printf("CAS successfully unloaded.\n"); } else { printf("UnloadResidentManager failed,\n"); printf("CAS error code is: 0X%X\n", -retval); } } CASLIB: C Library for CAS Developers 4-43 FAXLIB: HIGH-LEVEL LIBRARY 5 FOR CAS DEVELOPERS FAXLIB contains the high-level functions that provide simplified management of events and error handling. This chapter describes each function listed in alphabetical order. The format of the function descriptions is as follows: ╖ Description of the function. ╖ Summary provides the syntax for each function. ╖ Parameters describes the parameters for each function. ╖ Errors provides error information. ╖ Return Value can be used to test for error conditions or to provide the requested information. ╖ Remarks provides additional information on the function. ╖ See Also lists related functions. ╖ Example Program shows how the function is used. Compiling and Linking With FAXLIB To use functions from the FAXLIB library, applications must include the following files: ╖ CAS.H ╖ FAX.H ╖ FAXGLOB.H ╖ FAXDFLTS.H (for functions FAXSend and FAXSubmit only) ╖ FAXERROR.H (for function FAXError only) Link applications to the correct library for the memory model they are using. For example, the following are the compile and link commands for an application called SAMPLE.C written for the small memory model: cl /c /AS sample.c link sample ,, NUL, SFAXLIB, SCASLIB; FAXLIB: High-Level Library for CAS Developers 5-1 5-1 FAXLIB: High-Level Library for CAS Developers To use CL.EXE to both compile and link, type the following command: cl /AS sample.c /l SFAXLIB, SCASLIB NOTE: The FAXLIB functions use some functions from CASLIB. If you use FAXLIB functions, your application must be linked to both FAXLIB and CASLIB. FAXLIB Functions Grouped by Operation The FAXLIB functions can be divided into three groups: ╖ Event Management ╖ Event and Queue Queries ╖ Error Handling Event Management These functions simplify event management by hiding all control file management operations in lower levels and providing common defaults for many communications options. For example, to send a fax or file, the application must specify the recipient's phone number, the file(s) to be sent, and when to send the file(s). The FAXLIB function uses defaults for the remaining parameters. These defaults can be predefined set or defined by the application. FAXCancelTask Cancels a specified scheduled event. If the event is in progress, it is aborted. FAXCopyECS Copies all the information in an Event Control Structure to another structure. FAXFreeECS Frees all the memory used by an Event Control Structure. FAXSend Creates and submits a Send event to the Resident Manager. FAXSubmitTask Creates and submits an event from the settings of Tasksettings (along with the where, what, and when parameters) to the Resident Manager. 5-2 FAXLIB: High-Level Library for CAS Developers Event and Queue Queries These functions search the Task, Receive, or Log queues for information about an event. FAXGetEventControlInfo Gets that portion of information about an event that is in the control file's fixed-length part, the Event Control File (ECF) structure. FAXGetEventCover Gets the cover page text of an event. FAXGetEventFileInfo Gets the File Transfer Records (FTRs) for an event. Error Handling This function returns information on errors. FAXError Returns error or warning information on FAXLIB as well as CASLIB function calls. FAXLIB: High-Level Library for CAS Developers 5-3 FAXCancelTask Description Cancels a specified scheduled event. If the event is in progress, it is aborted. Summary #include <cas.h> #include <fax.h> int FAXCancelTask (EventHandle); Input Parameter int EventHandle; Event handle of the event to cancel. The functions FAXSend and FAXSubmitTask return this handle when they successfully submit an event. Output Parameter None. Errors If an error or warning condition occurs, FAXCancelTask sets the global variable FAXerrno. For a listing of the FAXerrno numbers and associated messages, refer to FAXERROR.H. Return Value Returns the event handle if successful; otherwise, returns 0. Remarks If the canceled event was pending at the time of the call, the function deletes the event's Control File. If the event was executing at the time of the call, this function calls CASAbortCurrentEvent which aborts it. CASAbortCurrentEvent does not delete the Control File but moves it to the Log Queue. NOTE: A Receive event and a Log are not initiated by the local application and so cannot be canceled by the local application. 5-4 FAXLIB: High-Level Library for CAS Developers FAXCancelTask Example Program The following program cancels the pending event. #include <stdio.h> #include <cas.h> #include <fax.h> #include <faxglob.h> #include <faxerror.h> main() { int handle, ErrorClass; BYTE queue = TASK_QUEUE; char *msg; handle = CASFindFirst(ANY_STATUS, SEARCH_FORWARD, queue); if (handle > 0) { handle = FAXCancelTask(handle); if (handle) { printf("The next send has been cancelled"); } else { msg = FAXError("CancelTask problem\n", NULL, &ErrorClass); printf(msg); free(msg); } } else { printf("Error occurred in CASFindFirst"); } } FAXLIB: High-Level Library for CAS Developers 5-5 FAXCopyECS Description Copies all the information in one Event Control Structure to another Event Control Structure. Summary #include <cas.h> #include <fax.h> ECS *FAXCopyECS (SourceECS, CopyECS); Input Parameters ECS *SourceECS; Pointer to an Event Control Structure. ECS *CopyECS; NULL or pointer to an Event Control Structure. Output Parameter ECS *CopyECS; If CopyECS is NULL on input, this function allocates memory and copies the given Event Control Structure. If not NULL on input, the Event Control Structure specified is filled with data identical to that in the *SourceECS. Errors If an error or warning condition occurs, FAXCopyECS sets the global variable FAXerrno. For a listing of the FAXerrno numbers and associated messages, refer to FAXERROR.H. If an error occurs, no information is copied and no memory is allocated. Return Value Returns a pointer to the copy structure if successful; otherwise, returns NULL. Remarks If CopyECS points to an Event Control Structure on input, the function copies the data from SourceECS into CopyECS. CopyECS and SourceECS must have an equal number of FTRLIST structures allocated. CopyECS must have enough space allocated for the cover page text, if any. When through with the structure, the application must free this memory. 5-6 FAXLIB: High-Level Library for CAS Developers FAXCopyECS FAXCopyECS is useful for making copies of the DefaultsECS and altering specific fields for use with FAXSubmitTask. This process allows submission of non-default events without altering the Toolkit defaults. See Also FAXSubmitTask, FAXFreeECS Example Program The following program makes a copy of the default event structure, sets the copy's destination name, phone number, and file list fields, and submits the event. #include <stdio.h> #include <cas.h> #include <fax.h> #include <faxglob.h> #include <faxdflts.h> #include <faxerror.h> CAS_DATE date = {1991, 1, 2}; /* January 2, 1991 */ main() { ECS *ecs; int retval, ErrorClass; char *errmsg; ecs = FAXCopyECS(&DefaultsECS, NULL); if (ecs) { retval = FAXSubmitTask(ecs, "Lab fax", "9, 645-8468", NULL, &date, NULL); if (retval > 0) { printf("Event 0X%X successfully submitted.\n", retval); } else { errmsg=FAXError("Problem submitting event.\n", NULL, &ErrorClass); printf(errmsg); free(errmsg); } } else { errmsg=FAXError("Problem copying defaults.\n", NULL, &ErrorClass); printf(errmsg); free(errmsg); } } FAXLIB: High-Level Library for CAS Developers 5-7 FAXError Description Returns error or warning information on FAXLIB as well as CASLIB function calls. Summary #include <cas.h> #include <fax.h> #include <faxerror.h> char * FAXError (MessageIn, MessageOut, ErrorClass); Input Parameters char *MessageIn; Pointer to a message provided by the caller. The function adds this message to the string it returns. If no additional message is desired, set this value to NULL. char *MessageOut; Pointer to a buffer to hold the returned error messages or NULL. If MessageOut is set to NULL, FAXError allocates the memory it needs for the messages. Output Parameters char *MessageOut; If non-NULL on entry, holds the returned error messages on exit. int *ErrorClass; Pointer to the type of error. Error classes are defined in CAS.H. Return Value Returns a pointer to the concatenated message. If the caller provided a buffer for the message in MessageOut, FAXError returns a pointer to that buffer. Strings are separated by the new-line character. Returns NULL if an error occurred. Remarks This function concatenates up to three strings and returns a pointer to the result. If the caller provides a message in MessageIn, the first string is that message. If FAXerrno is non-zero, a second string is added from the FAXerrlist table indexed by FAXerrno. If CASerrorcode is non-zero, a third string as well as the ErrorClass return parameter is obtained from the CASerrors table. The error tables are defined in FAXERROR.H. 5-8 FAXLIB: High-Level Library for CAS Developers FAXError If MessageOut is non-NULL, it is assumed to point to a buffer large enough (3 * MSGLENGTH) to hold the maximum number of messages. FAXError copies the messages into that buffer. The caller must free up this memory. Although not in the parameter list, two external variables are important input to this function. These are FAXerrno and CASerrorcode. When a FAXLIB function encounters an error or a warning condition, it sets FAXerrno to a positive non-zero value before returning. If there is no error or warning, it sets FAXerrno to 0. FAXError should be called immediately after any FAXLIB function that returns an error or warning, so no intervening FAXLIB function has the chance to reset FAXerrno. When a FAXLIB function receives an error return from a CASLIB function call, it sets CASerrorcode to the opposite (2's complement) of that return value, and sets FAXerrno to indicate which CASLIB function was in error. The error may not be fatal. The FAXLIB function may continue operation and return normally. FAXLIB functions indicate error by returning 0 or NULL. An application can use FAXError to obtain information about an error return from one of the CASLIB functions. To do this, set CASerrorcode to the opposite (2's complement) of the return value of the CASLIB function, set FAXerrno to the CAS function number, and call FAXError. See Also Every CASLIB and FAXLIB function can set error codes for which FAXError returns information. Example Program The following program scans the Log Queue for any events in an error condition and calls FAXError to retrieve the error information. #include <stdio.h> #include <stdlib.h> #include <cas.h> #include <fax.h> #include <faxglob.h> #include <faxerror.h> main() { int handle, ErrorClass; BYTE queue = LOG_QUEUE; char *msg; FAXLIB: High-Level Library for CAS Developers 5-9 FAXError ECF event, *retval; handle = CASFindFirst(ANY_STATUS, SEARCH_FORWARD, queue); if (handle > 0) { while (1) { retval = FAXGetEventControlInfo(handle, &queue, &event); if (retval > 0) { /* For every event in the log, check its status */ /* If status is negative, fetch and print err msg */ if (event.EventStatus < 0) { CASerrorcode = -event.EventStatus; msg = FAXError("Logged Event Error:\n", NULL, &ErrorClass); printf(msg); free(msg); } } handle = CASFindNext(queue); if (handle < 0) { break; } } } else { printf("No logged events"); } } 5-10 FAXLIB: High-Level Library for CAS Developers FAXFreeECS Description Frees all memory used by an Event Control Structure. Summary #include <cas.h> #include <fax.h> int FAXFreeECS (EventECS); Input Parameter ECS *EventECS; Pointer to an Event Control structure. All memory used by this structure must have been allocated from conventional memory using the standard C library or by the Toolkit function FAXCopyECS. Output Parameter None. Errors If an error or warning condition occurs, FAXFreeECS sets the global variable FAXerrno. For a listing of the FAXerrno numbers and associated messages, refer to FAXERROR.H. Return Value Returns FAIL only if the parameter EventECS is NULL. Otherwise, the function always returns SUCCESS. Remarks The EventECS must be in conventional memory. Using this function to free data in expanded memory has unpredictable results. See Also FAXCopyECS FAXLIB: High-Level Library for CAS Developers 5-11 FAXFreeECS Example Program The following program makes a copy of the default event structure and frees the copy. #include <stdio.h> #include <string.h> #include <cas.h> #include <fax.h> #include <faxglob.h> #include <faxdflts.h> #include <faxerror.h> main() { ECS *copy; int retval, ErrorClass; copy = FAXCopyECS(&DefaultsECS, NULL); if (copy) { if (FAXFreeECS(copy)) { printf("Copied Event Control Structure freed"); } } else { printf(FAXError("Problem copying defaults\n", NULL, &ErrorClass)); } } 5-12 FAXLIB: High-Level Library for CAS Developers FAXGetEventControlInfo Description Gets that portion of information about an event that is in the control file's fixed-length part, the Event Control File (ECF) structure. Summary #include <cas.h> #include <fax.h> ECF *FAXGetEventControlInfo (EventHandle, queue, EventInfo); Input Parameters int EventHandle; Event handle of an existing event. The event may be pending, currently executing, or completed. BYTE *queue; Pointer to the queue that the event is in, if known. The queue constants are TASK_QUEUE, RECEIVE_QUEUE, and LOG_QUEUE. If you do not know the queue holding the event, setting queue to UNKNOWN_QUEUE causes the function to search all the queues. ECF *EventInfo; Pointer to an ECF structure or NULL. If EventInfo points to an ECF structure on input, the function copies the ECF information into that structure. Otherwise (EventInfo is NULL) the function allocates an ECF structure, copies the information into it, and returns a pointer to that structure. Output Parameters BYTE *queue; The queue where the event was found. If the event was currently executing, queue is set to UNKNOWN_QUEUE. ECF *EventInfo; If on input this pointed to an ECF structure, on return it contains information about the event specified. This structure, along with the output of the functions FAXGetEventCover and FAXGetEventFileInfo can be used to create an ECS structure. FAXLIB: High-Level Library for CAS Developers 5-13 FAXGetEventControlInfo Return Value Returns a pointer to the ECF structure retrieved if successful, otherwise, returns NULL. Errors If an error or warning condition occurs, FAXGetEventControlInfo sets the global variable FAXerrno. For a listing of the FAXerrno numbers and associated messages, refer to FAXERROR.H. Remarks If you specify the queue, FAXGetEventControlInfo uses CASOpenFile on the specified event in that queue and reads the ECF information for that event. If you do not specify the queue (queue is UNKNOWN_QUEUE), FAXGetEventControlInfo calls CASFindFirst and CASFindNext to search all the queues until it finds the file associated with the specified event. It then opens that file and reads the ECF information. To obtain information about the current event, applications should call CASGetCurrentEventStatus. See Also CASFindFirst, CASFindNext, FAXGetEventCover, FAXGetEventFileInfo Example Program The following program retrieves information for the oldest event in the Log Queue and prints out the event type. #include <stdio.h> #include <string.h> #include <cas.h> #include <fax.h> #include <faxglob.h> #include <faxerror.h> main() { ECF info, *retval; int handle,ErrorClass; BYTE queue = LOG_QUEUE; char *msg; handle = CASFindFirst(ANY_STATUS, SEARCH_FORWARD, queue); if (handle > 0) { retval = FAXGetEventControlInfo(handle, &queue, &info); if (retval) { printf("The oldest logged event is a "); switch (info.EventType) { case SEND: 5-14 FAXLIB: High-Level Library for CAS Developers FAXGetEventControlInfo printf("SEND"); break; case RECEIVE: printf("RECEIVE"); break; case POLLED_SEND: printf("POLLED_SEND"); break; case POLLED_RECEIVE: printf("POLLED_RECEIVE"); } } else { msg = FAXError("GetEventInfo problem\n", NULL, &ErrorClass); printf(msg); free(msg); } } else { printf("No events in Log Queue"); } } FAXLIB: High-Level Library for CAS Developers 5-15 FAXGetEventCover Description Gets the cover page text of an event. Summary #include <cas.h> #include <fax.h> char *FAXGetEventCover (EventHandle, queue, CoverPtr); Input Parameters int EventHandle; Event handle of an existing event. BYTE *queue; Pointer to the queue that the event is in, if known. The queue constants are TASK_QUEUE, RECEIVE_QUEUE, and LOG_QUEUE. If the queue holding the event is not known, setting queue to UNKNOWN_QUEUE causes the function to search all the queues. char *CoverPtr; Pointer to the buffer for the cover page text or NULL. Output Parameters BYTE *queue; The queue where the event was found. char *CoverPtr; If not NULL on input, this buffer contains the text of the cover page. Errors If an error or warning condition occurs, FAXGetEventCover sets the global variable FAXerrno. For a listing of the FAXerrno numbers and associated messages, refer to FAXERROR.H. Return Value Returns a pointer to the cover page text read; returns NULL if an error occurred. 5-16 FAXLIB: High-Level Library for CAS Developers FAXGetEventCover Remarks If you specify the queue, the function calls CASOpenFile to open the specified event in that queue. If you do not specify the queue (queue is UNKNOWN_QUEUE), the function searches all the queues until it finds the specified event file. If CoverPtr is not NULL, it is assumed to point to enough space to hold the cover page text. The function reads the cover text into that buffer and returns its pointer. If CoverPtr is NULL, the function allocates the memory itself, reads the cover page text into that memory, and returns its pointer. The caller must free up this memory. If the caller lets the function allocate the memory for the CoverPtr buffer, it does not have to know how large the cover page is. The function finds this information from the event control information in the file and allocates the needed space itself. If the caller provides the buffer, the buffer must be large enough to store the information without overwriting other data. This function cannot retrieve an event's cover page text if the event is currently executing. See Also CASFindFirst, CASFindNext, FAXGetEventControlInfo, FAXGetEventFileInfo Example Program The following program retrieves and displays the cover page text for the last occurring event. #include <stdio.h> #include <stdlib.h> #include <malloc.h> #include <cas.h> #include <fax.h> #include <faxglob.h> #include <faxerror.h> main() { int handle,ErrorClass; BYTE queue = TASK_QUEUE; char *cover, *msg; FAXLIB: High-Level Library for CAS Developers 5-17 FAXGetEventCover handle = CASFindFirst(ANY_STATUS, SEARCH_BACKWARD, queue); if (handle > 0) { cover = FAXGetEventCover(handle, &queue, NULL); if (cover) { printf("cover for most future send is:\n%s", cover); free(cover); } else { msg = FAXError("GetEventCover problem\n", NULL, &ErrorClass); printf(msg); free(msg); } } else { printf("No pending events"); } } 5-18 FAXLIB: High-Level Library for CAS Developers FAXGetEventFileInfo Description Gets the File Transfer Records (FTRs) for an event. Summary #include <cas.h> #include <fax.h> FTRLIST * FAXGetEventFileInfo (EventHandle, queue, FTRs, WhichFTRFirst, HowManyFTRS); Input Parameters EventHandle; Event handle of an existing event. BYTE *queue; Pointer to the queue that the event is in, if known. The queue constants are TASK_QUEUE, RECEIVE_QUEUE, and LOG_QUEUE. If you do not know the queue holding the event, setting queue to UNKNOWN_QUEUE causes the function to search all the queues. FTRLIST *FTRs; Pointer to a linked list of one or more FTR structures or NULL. int WhichFTRFirst; Which FTR in the given event to retrieve first. (The first FTR is number 0.) int *HowManyFTRs; Pointer to the number of FTR(s) to retrieve or 0 for all of them starting with WhichFTRFirst. Output Parameters BYTE *queue; The queue where the event was found. FTRLIST *FTRs; If FTRs was not NULL on entry, on return the list it pointed to contains the information for the FTRs requested. int *HowManyFTRs; How many FTR(s) were actually retrieved. This may be fewer than the number requested. Errors If an error or warning condition occurs, FAXGetEventFileInfo sets the global variable FAXerrno. For a listing of the FAXerrno numbers and associated messages, refer to FAXERROR.H. FAXLIB: High-Level Library for CAS Developers 5-19 FAXGetEventFileInfo Return Value Returns a pointer to the list of FTR(s) retrieved if successful; otherwise, returns NULL. If the caller allocated a list and passed its pointer as the parameter FTRs, then this pointer is returned. If the caller passed NULL for the parameter FTRs, then the function allocates memory for the list and returns a pointer to the first structure in that list. The caller must free up this memory. Remarks If you specify the queue, the function calls CASOpenFile on the specified event in that queue. If you do not specify the queue (queue is UNKNOWN_QUEUE), the function calls CASFindFirst and CASFindNext to search all the queues in turn until it finds the file associated with the specified event. It then opens that ECF and finds the information on the FTR(s) requested. If FTRs is NULL, the function allocates the memory needed for HowManyFTRs structures. If FTRs is not NULL, it is assumed to point to a list of structures. In this case the caller must make sure that this list contains at least HowManyFTRs structures. The function attempts to read HowManyFTRs File Transfer Records from the event file, starting at WhichFTRFirst. If there is a difference between the number designated and the number read, the function sets HowManyFTRs to the number read. If the event is currently executing, this function cannot retrieve the event's file information. NOTE: Do not use this function for getting the names of received files to open, move, or delete them. For these activities, use CASOpenFile, CASMoveReceivedFile, CASDeleteFile, and CASDeleteAllFiles. Refer to the appropriate reference page for additional information on these functions. See Also CASFindFirst, CASFindNext, FAXGetEventControlInfo, FAXGetEventCover 5-20 FAXLIB: High-Level Library for CAS Developers FAXGetEventFileInfo Example Program The following program retrieves the file information structure for the first file to be sent in a pending event. #include <stdio.h> #include <stdlib.h> #include <malloc.h> #include <cas.h> #include <fax.h> #include <faxglob.h> #include <faxerror.h> main() { FTRLIST ftr, *retval; int handle, ErrorClass; BYTE queue = TASK_QUEUE; char *msg; int how_many = 1; handle = CASFindFirst(ANY_STATUS, SEARCH_FORWARD, queue); if (handle > 0) { retval = FAXGetEventFileInfo(handle, &queue, &ftr, 0, &how_many); if (retval && (how_many == 1)) { printf("The file that will be sent is: %s", ftr.OneFTR.FileName); } else { msg = FAXError("GetEventFileInfo problem\n", NULL, &ErrorClass); printf(msg); free(msg); } } else { printf("No pending events"); } } FAXLIB: High-Level Library for CAS Developers 5-21 FAXSend Description Creates and submits a Send event to the Resident Manager. Summary #include <cas.h> #include <fax.h> #include <faxdflts.h> int FAXSend (to, PhoneNumber, files, date, time); Input Parameters char *to; NULL or pointer to the name of the destination. For fax transmissions, this name is printed after "to:" at the top of each page. char *PhoneNumber; NULL or pointer to a phone number following the CAS phone number specification. FILELIST *files; NULL or pointer to one or more files to send, as a linked list of filenames and file types. CAS_DATE *date; NULL or pointer to a structure containing the year, month, and day for the event to execute. CAS_TIME *time; NULL or pointer to a structure containing the hour, minute, and second for the event to execute. Output Parameter None. Return Value Returns the event handle if successful; otherwise, returns 0. Errors If an error or warning condition occurs, FAXSend sets the global variable FAXerrno. For a listing of the FAXerrno numbers and associated messages, refer to FAXERROR.H. 5-22 FAXLIB: High-Level Library for CAS Developers FAXSend Remarks Using the parameters along with values in the DefaultsECS structure, this function submits the event to the Resident Manager. For any of the parameters that are set to NULL, the FAXSend function uses the values of the corresponding fields in the DefaultsECS. To change the defaults from their predefined values, assign the desired values to the fields of the DefaultsECS structure. Those new values are the defaults for the rest of the current run of the application. To change fields in the DefaultsECS structure to the original defaults, either change the fields directly to the original settings as defined in FAXDFLTS.H or make a copy of the defaults with FAXCopyECS before changing the fields. NOTE: Setting the time earlier than the current time will cause the event to execute immediately if the date is set to the current date. Therefore, Intel recommends that you change the date before you change the time or you may accidentally send an event before you intend to. Setting the date and time to all zeroes causes the event to execute immediately. See Also FAXSubmitTask, FAXCopyECS Program Example The following program sends two ASCII files to a fax machine on January 2, 1991. #include <stdio.h> #include <cas.h> #include <fax.h> #include <faxglob.h> #include <faxdflts.h> #include <faxerror.h> CAS_DATE date = {1991, 1, 2}; CAS_TIME time = {0, 0, 0}; FILELIST file2 = {"c:\\autoexec.bat", ASCII, NULL}, file1 = {"c:\\config.sys", ASCII, &file2}; FAXLIB: High-Level Library for CAS Developers 5-23 FAXSend char *errmsg; main() { int retval, ErrorClass; retval = FAXSend("Lab fax", "9, 645-8468", &file1, &date, &time); if (retval > 0) { printf("Event 0X%X successfully submitted.", retval); } else { errmsg=FAXError("Problem submitting event\n", NULL, &ErrorClass); printf(errmsg); free(errmsg); } } 5-24 FAXLIB: High-Level Library for CAS Developers FAXSubmitTask Description Creates and submits an event from the settings of Tasksettings along with the where, what, and when parameters to the Resident Manager. Summary #include <cas.h> #include <fax.h> #include <faxdflts.h> int FAXSubmitTask (TaskSettings, to, PhoneNumber, files, date, time); Input Parameters ECS *TaskSettings; Pointer to an Event Control Structure (ECS) containing all the information needed for an event not provided by the other parameters. If any of the following pointer parameters are set to NULL, the values in the corresponding fields of this structure are used. char *to; NULL or pointer to name of the destination. For fax transmissions, this name is printed after "to:" at the top of each page. char *PhoneNumber; NULL or pointer to a phone number following the CAS phone number specification. FILELIST *files; NULL or pointer to one or more files to send, as a linked list of filenames and file types. CAS_DATE *date; NULL or pointer to a structure containing the year, month, and day for the event to execute. CAS_TIME *time; NULL or pointer to a structure containing the hour, minute, and second for the event to execute. Output Parameter ECS *TaskSettings; If any of the other parameters were set (non-NULL), those values replace the corresponding fields of this ECS. FAXLIB: High-Level Library for CAS Developers 5-25 FAXSubmitTask Return Value Returns the event handle if successful; otherwise, returns 0. Errors If an error or warning condition occurs, FAXSubmitTask sets the global variable FAXerrno. For a listing of the FAXerrno numbers and associated messages, refer to FAXERROR.H. Remarks Creates an ECF from the settings of the TaskSettings along with the other parameters that are not NULL and submits the event to the Resident Manager. Setting the parameters to a non-NULL value changes the values of the corresponding field in TaskSettings. To create an ECS with all the fields already filled in with valid values, use FAXCopyECS with the DefaultsECS as the source. NOTE: Setting the time earlier than the current time will cause the event to execute immediately if the date is set to the current date. Therefore, Intel recommends that you change the date before you change the time or you may accidentally send an event before you intend to. Setting the date and time to all zeroes causes the event to execute immediately. See Also FAXSend, FAXCopyECS Example Program The following program sets the destination phone number, the to field, and the transmission date (January 2, 1991) of the default event structure and submits the event. #include <stdio.h> #include <cas.h> #include <fax.h> #include <faxglob.h> #include <faxdflts.h> #include <faxerror.h> CAS_DATE date = {1991, 1, 2}; 5-26 FAXLIB: High-Level Library for CAS Developers FAXSubmitTask main() { int retval, ErrorClass; char *errmsg; retval = FAXSubmitTask(&DefaultsECS, "Lab fax", "9, 645- 8468", NULL, &date, NULL); if (retval > 0) { printf("Event 0X%X successfully submitted.", retval); } else { errmsg=FAXError("Problem submitting event\n", NULL, &ErrorClass); printf(errmsg); free(errmsg); } } FAXLIB: High-Level Library for CAS Developers 5-27 PBLIB: LIBRARY FOR 6 PHONEBOOK MANAGEMENT PBLIB contains the phonebook functions. While the Intel phonebook format is described in the DCA/Intel Communicating Applications Specification, it is not officially part of the specification. The Intel phonebook format is used by Intel's application software. The Intel phonebook format may or may not be compatible with phonebook formats used by other CAS compatible boards. PBLIB uses the Intel phonebook format described in the DCA/Intel Communicating Applications Specification. NOTE: Be advised that using PBLIB may result in creating phonebooks that are compatible only with Intel phonebooks. This chapter describes the phonebook functions which are listed in alphabetical order. The format of the function descriptions is as follows: ╖ Description of the function. ╖ Summary provides the syntax for each function. ╖ Parameters describes the parameters for each function. ╖ Errors provides error information. ╖ Return Value can be used to test for error conditions or to provide the information returned. ╖ Remarks provides additional information on the function. ╖ See Also lists related functions. ╖ Example Program shows how the function is used. NOTE: To understand the concepts and terms used in this chapter, you must be familiar with the DCA/Intel Communication Applications Specification information on the Intel phonebook format described in that document. PBLIB: Library For Phonebook Management 6-1 6-1 PBLIB: Library For Phonebook Management Compiling and Linking With PBLIB To use functions from the PBLIB library, applications must include the following files: ╖ PHONEBK.H ╖ PBDFLT.H ╖ PBGLOBAL.H ╖ PBERROR.H Link applications to the correct library for the memory model they are using. For example, the following are the compile and link commands for an application called SAMPLE.C written for the small memory model: cl /c /AS sample.c link sample ,, NUL, SPBLIB; To use CL.EXE to both compile and link, type the following command: cl /AS sample.c /l SPBLIB Phonebook Functions Grouped by Operation Phonebooks are databases that CAS applications can use to make event generation easier for end-users. The phonebook functions provide an interface to phonebook files which have the format described in the DCA/Intel Communicating Applications Specification. The phonebook support functions can be divided into three groups: ╖ General management ╖ Entry queries ╖ Entry modification General Management These functions let you manage phonebooks including creating and opening a phonebook. PbBufferOffsets Sets up the phonebook structure's buffer for all phonebook entry queries and modification. PbCreatePhonebook Creates a phonebook file consisting only of a header and 0 entries. PbGarbageCollect Eliminates unused space in a phonebook file. PbOpenPhonebook Opens an existing phonebook file for query or modification. Entry Queries These functions look up pieces of information on specified entries. PbFindFirstOrNext Gets the first or the next entry whose name matches a given string specification, including wildcards. PbFreePBE Frees the memory used by a phonebook entry structure. 6-2 PBLIB: Library For Phonebook Management PbGetEntry Gets all the information on an entry using either the name or the record ID for a given entry. PbLookUpSendInfo Gets an entry's phone number and hardware type using either the name or record ID for a given entry. Entry Modification These functions add, change, or remove entries. PbAddEntry Adds a group or person into the specified phonebook and updates any other affected entries. PbAddToGroup Adds a person entry to a group and updates any other affected entries. PbModifyEntry Changes one or more fields in a phonebook entry and updates any other affected entries. PbRemoveEntry Deletes an existing entry and updates any other affected entries. PbRemoveFromGroup Deletes a person entry from a group and updates any other affected entries. Phonebook Buffering In the Toolkit, the phonebook structure uses a memory buffer that is variable in length for the file offsets of entries. For details about how to set the size of this buffer and how it works see the reference page for the function PbBufferOffsets. NOTE: All phonebook query functions perform better if the phonebook's memory buffer is used (PbBufferOffset). PBLIB: Library For Phonebook Management 6-3 PbAddEntry Description Adds a group or person entry into the specified phonebook updating any other affected entries. Summary #include <phonebk.h> #include <pbglobal.h> int PbAddEntry (pb, entry); Input Parameters PB *pb; Pointer to a phonebook structure. PBE *entry; Pointer to a phonebook entry structure. Complete except for the record ID and length fields, which the function sets. The entry can be a person or group. For information on person and group records, refer to the Phonebook Format section of the DCA/Intel Communicating Applications Specification. Output Parameter PBE *entry; Pointer to the added phonebook entry structure with the record ID and length fields filled in. Errors For a listing of the Pberrno numbers and associated messages, refer to PBERROR.H. Return Value Returns SUCCESS or FAIL. Remarks The caller must create a phonebook entry structure and must set the fields (except the record ID and length fields) to valid values except the record ID and length fields. If the entry is a group, it must have at least one member in its membership list. Also, if the entry is a group, the application need not set the hardware type field. PbAddEntry will set it. All members in the group's membership list must be person entries in the phonebook. All entries must have unique names, with uppercase/lowercase distinction ignored. The function returns an error if an entry already exists with the same name or if the name differs only in case. NOTE: You must open the phonebook with PbOpenPhonebook before you can use this function. 6-4 PBLIB: Library For Phonebook Management PbAddEntry See Also PbOpenPhonebook, PbModifyEntry, PbRemoveEntry Example Program The following program prompts for a name and phone number, adds the entry to the default phonebook, and displays whether the entry was successfully added. #include <stdio.h> #include <phonebk.h> #include <pberror.h> #include <pbglobal.h> char *pbname = "c:\\connect\\default.pb"; main() { PB phonebook, *result; PBE entry; int i; if (result = PbOpenPhonebook(&phonebook, pbname)) { entry.id = 0; entry.members = 0; entry.length = 0; entry.type = PERSONENTRY; entry.HardwareType = FAXONLY; printf("Enter name of entry - "); gets(entry.name); printf("\nEnter phone number - "); gets(entry.PhoneNumber); if (phonebook.header.fields > 0) entry.fields = (char **)malloc(phonebook. header.fields * sizeof(char *)); for (i=0; i<phonebook.header.fields; i++) entry.fields[i] = (char *)malloc(60 * sizeof(char)); printf("Comments: - "); gets(entry.fields[0]); printf("Voice phone: - "); gets(entry.fields[1]); if (PbAddEntry(&phonebook,&entry)) { printf("\n%s added to %s \n", entry.name, pbname); printf("RecordID=%d Record Length=%d\n", entry.id, entry.length); } else { printf("\nError adding entry \n"); printf("Message is %s \n", PBerrlist[Pberrno]); } for (i=0; i<phonebook.header.fields; i++) if(entry.fields[i]) free(entry.fields[i]); if(entry.fields) free(entry.fields); fclose(phonebook.fp); PBLIB: Library For Phonebook Management 6-5 PbAddEntry } else { printf("\nError opening phonebook \n"); printf("Message is %s \n", PBerrlist[Pberrno]); } } 6-6 PBLIB: Library For Phonebook Management PbAddToGroup Description Adds a person entry to a group updating any other affected entries. Summary #include <phonebk.h> #include <pbglobal.h> int PbAddToGroup (pb, groupID, memberID); Input Parameter PB *pb: Pointer to a phonebook structure. int groupID; Record ID of a group phonebook entry. int memberID; Record ID of a person entry to add to the specified group. Output Parameter PB *pb; Modified phonebook structure. Errors For a listing of the Pberrno numbers and associated messages, refer to PBERROR.H. Return Value Returns SUCCESS or FAIL. The function fails if either the person entry or the group entry doesn't exist, if they are not the right entry type (person or group), or if the person is already a member of that group. Remarks This function adds a specified member to the group's membership list and adds the group to the membership list of the member. This function uses the entry's and group's record ID numbers to access them. If only the name of the entry or the group is known, the application can find the record ID by using either the PbGetEntry or the PbFindFirstOrNext functions. NOTE: You must open the phonebook with PbOpenPhonebook before you can use this function. If the hardware type of the person added is FAXONLY and that of the group is HASCCC, the function changes the group's type to FAXONLY. PBLIB: Library For Phonebook Management 6-7 PbAddToGroup See Also PbOpenPhonebook, PbAddEntry, PbRemoveFromGroup, PbGetEntry, PbFindFirstOrNext Example Program The following program prompts for a person entry and a group entry. It then adds the person entry to that group and displays whether the addition was a success. #include <stdio.h> #include <phonebk.h> #include <pberror.h> #include <pbglobal.h> char *pbname = "c:\\connect\\default.pb"; main() { PB phonebook, *result; PBE *person, *group; int rid = -1; char aperson[32]; char agroup[32]; if (result = PbOpenPhonebook(&phonebook, pbname)) { printf("Enter person adding to group - "); gets(aperson); printf("\nEnter group adding person to - "); gets(agroup); if (person = PbGetEntry(&phonebook, NULL, aperson, rid)) { if (group = PbGetEntry(&phonebook, NULL, agroup, rid)) { if(PbAddToGroup(&phonebook,group->id, person->id)) { printf("Successfully added %s to %s\n", aperson, agroup); PbFreePBE(&phonebook, group); } else { printf("\nError adding to group \n"); printf("Message is %s \n", PBerrlist[Pberrno]); } } else { printf("\nError getting group \n"); printf("Message is %s \n", PBerrlist[Pberrno]); } PbFreePBE(&phonebook, person); } else { printf("\nError getting person \n"); printf("Message is %s \n", PBerrlist[Pberrno]); } 6-8 PBLIB: Library For Phonebook Management PbAddToGroup fclose(phonebook.fp); } else { printf("\nError opening phonebook \n"); printf("Message is %s \n", PBerrlist[Pberrno]); } } PBLIB: Library For Phonebook Management 6-9 PbBufferOffsets Description Sets up the phonebook structure's offset buffer for all phonebook entry queries and modifications. The offset buffer stores phonebook information in memory to improve performance. Summary #include <phonebk.h> #include <pbglobal.h> PB *PbBufferOffsets (pb, buffer, OBufferSize); Input Parameters PB *pb; Pointer to a phonebook structure of an open phonebook. LONGWORD *buffer; NULL or pointer to buffer of OBufferSize bytes. Directs the function to allocate memory from conventional memory by setting buffer to NULL. WORD OBufferSize; Size to make buffer, in bytes, from 4 to a maximum of 4000. If not a multiple of 4, function rounds the size down to the nearest multiple of 4. Output Parameter PB *pb; The phonebook structure with OBuffer and OBufferSize initialized. Errors For a listing of the Pberrno numbers and associated messages, refer to PBERROR.H. Return Value If successful, returns the pointer to the phonebook structure. Otherwise, returns NULL. Remarks PBLIB functions that query or modify a phonebook entry find the entry by its offset in the phonebook file. The entry's record ID is an index into the array of offsets in the phonebook file header. If the offset buffer has been set up by calling PbBufferOffsets and the offset sought is currently in the buffer, the functions retrieve the offset sought from there. If the offset is not there, the functions read the portion of the offset array that contains the offset into the offset buffer and then retrieve it. PBLIB functions perform significantly better if the offset buffer is used. For best results, set OBufferSize large enough to hold as many offsets as the phonebook is expected to have. For example, to hold offsets for 100 entries, set OBufferSize to 400. If the offset buffer is not used, PBLIB functions need to make more accesses directly to the phonebook file. 6-10 PBLIB: Library For Phonebook Management PbBufferOffsets This function reads OBufferSize bytes of the phonebook file's offset array into a memory buffer and assigns that buffer to the OBuffer field of the phonebook structure. The caller either provides the memory for this buffer or directs the function to allocate the memory by setting buffer to NULL. See Also PbOpenPhonebook Example Program The following program opens the default phonebook, initializes an offset buffer to 500 bytes, and displays the buffer's contents. #include <stdio.h> #include <phonebk.h> #include <pberror.h> #include <pbglobal.h> char *pbname = "c:\\connect\\default.pb"; main() { PB phonebook, *result; int i, buffsize = 500; result = PbOpenPhonebook(&phonebook, pbname); if (result) { result = PbBufferOffsets(&phonebook, NULL, buffsize); PBLIB: Library For Phonebook Management 6-11 PbBufferOffsets if (result) { printf("Contents of offset buffer are:\n"); for (i=0; i<(buffsize/sizeof(LONGWORD)); i++) { if (!(i%10)) printf("\n"); printf(" %5.4d ", phonebook.OBuffer[i]); } } fclose(phonebook.fp); } } 6-12 PBLIB: Library For Phonebook Management PbCreatePhonebook Description Creates a phonebook file consisting only of a header and 0 entries. Summary #include <phonebk.h> #include <pbglobal.h> PB *PbCreatePhonebook (pb, name); Input Parameters PB *pb; NULL or pointer to a phonebook structure. char *name; Pointer to a full path and name to give a new phonebook. Output Parameter PB *pb; If this pointed to a phonebook structure on entry, on return it is filled with the information about the new phonebook. If the pointer pb is NULL, the function allocates a phonebook structure and returns that structure's pointer. Errors For a listing of the Pberrno numbers and associated messages, refer to PBERROR.H. Return Value If a phonebook structure was provided by pb, it returns pb. If pb was NULL, it returns a pointer to the structure allocated. Remarks The phonebook file is left open for reading and writing. The buffer for offsets is initially NULL. OBufferSize is set to 0. Intel's CAS application for the Connection CoProcessor is CONNECT.EXE. When creating new phonebooks, applications must observe a few restrictions if they intend to share phonebooks with CONNECT. They are as follows: ╖ Name phonebook files with the extension .PB (for example, sample.pb.) ╖ Keep phonebook files in the default directory for CAS software. This directory is found in the CAS External Data Block. ╖ Use only two of the ten "ASCIIZ variable fields." CONNECT names these "Voice Phone" and "Comment." PbCreatePhonebook uses a global structure for the phonebook header with these names pre-initialized. PBLIB: Library For Phonebook Management 6-13 PbCreatePhonebook See Also PbOpenPhonebook Example Program The following program creates a new phonebook file in the c:\connect directory under the name "sample.pb". #include <stdio.h> #include <phonebk.h> #include <pberror.h> #include <pbglobal.h> char *pbname = "c:\\connect\\sample.pb"; main() { PB phonebook, *result; result = PbCreatePhonebook(&phonebook, pbname); if (result) { printf("New phonebook %s created\n", pbname); fclose(phonebook.fp); } else printf("CreatePhonebook error, msg is:\n%s", PBerrlist[Pberrno]); } 6-14 PBLIB: Library For Phonebook Management PbFindFirstOrNext Description Gets the first or the next entry whose name matches a given string specification, including wildcards. Summary #include <phonebk.h> #include <pbglobal.h> PBE *PbFindFirstOrNext (pb, pbe, name, recordID); Input Parameters PB *pb; Pointer to a phonebook structure. PBE *pbe; NULL or pointer to a phonebook entry structure. If pbe is NULL on input, the function allocates the memory it needs, reads the data into that memory, and returns its pointer. If a pointer to a phonebook entry structure is provided, the requested data is returned in that structure. char *name; Pointer to a string specification of name whose entry is sought. This string specification may contain the wildcards ? and *. int *recordID; Pointer to a record ID from 0 to 999 or -1. If recordID is -1, the function performs a "FindFirst" event by finding the first entry that matches the name string. If none are found, it sets Pberrno to NOENTRYFOUND and returns NULL. Output Parameters PBE *pbe; If NULL, the function allocates memory, reads the data into that memory, and returns its pointer. If not NULL on input, holds the data for the entry requested. int *recordID; A record ID from 0 to 999 or -1. Errors For a listing of the Pberrno numbers and associated messages, refer to PBERROR.H. Return Value If the search is successful, the function returns a pointer to the PBE structure holding the data for the requested entry. Otherwise it returns NULL. PBLIB: Library For Phonebook Management 6-15 PbFindFirstOrNext NOTE: You must open the phonebook with PbOpenPhonebook before you can use this function. All phonebook query functions perform better if the phonebook's offset buffer is being used (PbBufferOffsets). For information on the buffer, refer to the PbBufferOffsets reference page. Remarks If the exact name is specified, the function finds and returns the information on the entry by that name. This function performs two different events, depending on the setting on input of the parameter recordID. If recordID is a valid record ID (0 - 999), then it is assumed to have been set by a previous call to this function. The function performs a "FindNext" event. It first reads the entry indicated by recordID into the phonebook entry structure, if there is an entry for that record ID. If not, the function sets Pberrno to NOENTRYFOUND and returns NULL. It then searches for another entry that matches the name string. If it finds one, it sets recordID to the record ID of the entry found. If it doesn't find any, it sets Pberrno to NOMOREMATCH. If recordID is -1, it performs a "Find First" event. See Also PbOpenPhonebook, PbLookUpSendInfo, PbGetEntry, and PbFreePBE Example Program The following program uses the wildcard "*" to search the phonebook for all matching entries and prints the ID number, name, and phone number of each matching entry. #include <stdio.h> #include <phonebk.h> #include <pberror.h> #include <pbglobal.h> char *pbname = "c:\\connect\\default.pb"; main() { PB phonebook, *result; PBE *entry; int rid = -1; char name[32]; if (result = PbOpenPhonebook(&phonebook, pbname)) { printf("\nEnter search name using wildcards * or ? - "); gets(name); printf("\nMatching entries are: \n"); printf("Record Name "); printf(" Phone Number\n"); do { if (entry = PbFindFirstOrNext(&phonebook, 6-16 PBLIB: Library For Phonebook Management PbFindFirstOrNext NULL, name, &rid)) { printf("%6d %-32s %-32s \n",entry->id, entry->name, entry->PhoneNumber); } if (Pberrno == NOMOREMATCH) break; } while (entry); printf("No more matching entries\n"); PbFreePBE(&phonebook, entry); fclose(phonebook.fp); } else { printf("\nError opening phonebook \n"); printf("Message is %s \n", PBerrlist[Pberrno]); } } PBLIB: Library For Phonebook Management 6-17 PbFreePBE Description Frees the memory used by a phonebook entry structure. Summary #include <phonebk.h> #include <pbglobal.h> void PbFreePBE (pb, entry); Input Parameters PB *pb; Pointer to a phonebook structure. PBE *entry; Pointer to a phonebook entry structure. Output Parameters None. Errors For a listing of the Pberrno numbers and associated messages, refer to PBERROR.H. Return Value None. Remarks The memory used by the entry must be conventional memory, allocated by the standard C functions malloc, calloc, or realloc. The memory can also be allocated by any PBLIB function that uses those standard C functions, such as PbGetEntry or PbFindFirstOrNext. This function has no effect on the entry information in the phonebook file or the phonebook structure. This function frees the memory used by the entry and all its variable- length fields. NOTE: You must open the phonebook with PbOpenPhonebook before you can use this function. If either the phonebook or entry parameters are NULL, the function sets Pberrno to INVALIDPARAMETERS and doesn't free any memory. If any of the pointer fields of the entry to be initialized are NULL, the function sets Pberrno to NULLPOINTER but frees the initialized pointers. See Also PbGetEntry, PbFindFirstOrNext 6-18 PBLIB: Library For Phonebook Management PbFreePBE Example Program The following program gets the first entry (record ID of 0) in the phonebook, then frees the memory used by that entry. #include <stdio.h> #include <phonebk.h> #include <pberror.h> #include <pbglobal.h> char *pbname = "c:\\connect\\default.pb"; main() { PB phonebook, *result; PBE *entry; int rid = 0; result = PbOpenPhonebook(&phonebook, pbname); if (result) { entry = PbGetEntry(&phonebook, NULL, NULL, rid); if (entry) { printf("The first entry in %s is %s\n", pbname, entry->name); PbFreePBE(&phonebook, entry); } else { printf("First entry in %s not found\n"); } fclose(phonebook.fp); } } PBLIB: Library For Phonebook Management 6-19 PbGarbageCollect Description Eliminates unused space in a phonebook file that can accumulate through entry deletions and modifications. Summary #include <phonebk.h> #include <pbglobal.h> int PbGarbageCollect (pbFilename); Input Parameters char *pbFilename; Pointer to a name of a closed phonebook file. Output Parameter None. Errors For a listing of the Pberrno numbers and associated messages, refer to PBERROR.H. Return Value Returns SUCCESS or FAIL. To perform the garbage collection, PbGarbageCollect must create a new copy of the phonebook on the disk. The function checks for disk space before creating the new phonebook. If there is not enough disk space to perform the operation, the function doesn't create the copy and returns FAIL. NOTE: The phonebook file must be closed to use this function, and, upon return, the phonebook file is left closed. See Also None. 6-20 PBLIB: Library For Phonebook Management PbGarbageCollect Example Program The following program removes all unused bytes from the default phonebook. #include <stdio.h> #include <phonebk.h> #include <pberror.h> #include <pbglobal.h> char *pbname = "c:\\connect\\default.pb"; main() { PB phonebook, *result; result = PbOpenPhonebook(&phonebook, pbname); if (result) { printf("Phonebook %s has %d unused bytes\n", pbname, phonebook.header.FreeBytes); fclose(phonebook.fp); if (PbGarbageCollect(pbname)) { result = PbOpenPhonebook(&phonebook, pbname); if (result) { printf("\n%s now has %d unused bytes\n", pbname, phonebook.header.FreeBytes); } else { printf("GarbageCollect error,msg is:\n%s", PBerrlist[Pberrno]); } } } else { printf("OpenPhonebook error, msg is:\n%s", PBerrlist[Pberrno]); } } PBLIB: Library For Phonebook Management 6-21 PbGetEntry Description Gets all the information on an entry, using either the name or the record ID of a given entry. Summary #include <phonebk.h> #include <pbglobal.h> PBE *PbGetEntry (pb, pbe, name, recordID); Input Parameters PB *pb; Pointer to a phonebook structure. PBE *pbe; NULL or pointer to a phonebook entry structure. char *name; NULL or pointer to a name of a person or group to look up. No wildcards are allowed in the name. int recordID; A record ID from 0 to 999, or -1. Use name to look up the information. Output Parameter PBE *pbe; If not NULL on input, holds the data on the requested entry. If NULL, the function allocates memory and returns the pointer to that memory. Errors For a listing of the Pberrno numbers and associated messages, refer to PBERROR.H. Return Value If successful, returns a pointer to the phonebook entry structure holding data for the requested entry. Otherwise, returns NULL. Remarks If both recordID and name are specified, the record ID takes precedence. The complete entry information for a group includes the group's membership list, so this function is useful for obtaining the record IDs of all the members of a group. If the parameter pbe is not NULL on input, it is assumed to point to a phonebook entry structure. The data from the requested entry is read into that structure, and the function returns a pointer to it. If pbe is NULL on input, the function allocates the memory it needs for the requested entry, reads the data into that, and returns its pointer. 6-22 PBLIB: Library For Phonebook Management PbGetEntry NOTE: You must open the phonebook with PbOpenPhonebook before you can use this function. See Also PbOpenPhonebook, PbFindFirstOrNext, PbLookUpSendInfo Example Program The following program gets the entry requested by name in the phonebook and prints the phone number. #include <stdio.h> #include <phonebk.h> #include <pberror.h> #include <pbglobal.h> char *pbname = "c:\\connect\\default.pb"; main() { PB phonebook, *result; PBE *entry; int rid = -1; char name[32]; if (result = PbOpenPhonebook(&phonebook, pbname)) { printf("\nEnter exact name "); printf("(no wild cards allowed) :"); gets(name); printf("\nName "); printf(" Phone Number\n"); if (entry = PbGetEntry(&phonebook, NULL, name, rid)) { printf("%-32s %-32s \n", entry->name, entry->PhoneNumber); PbFreePBE(&phonebook, entry); } else { printf("\nError getting entry %s\n", name); printf("Message is %s \n", PBerrlist[Pberrno]); } fclose(phonebook.fp); } else { printf("\nError opening phonebook \n"); printf("Message is %s \n", PBerrlist[Pberrno]); } } PBLIB: Library For Phonebook Management 6-23 PbLookUpSendInfo Description Gets an entry's phone number and hardware type using either the name or record ID for a given entry. Summary #include <phonebk.h> #include <pbglobal.h> int PbLookUpSendInfo (pb, name, recordID, PhoneNumber, CommHardware); Input Parameters PB *pb; Pointer to a phonebook structure. char *name; Pointer to a name of the entry (person or group) to look up. int *recordID; Pointer to a -1 or record ID of entry record to look up. Output Parameters char *name; If the record ID was used, the name of the entry found. int *recordID; If the name was used, the record ID of the entry found. char *PhoneNumber; Pointer to phone number of entry found. String must be large enough to hold 47 characters. BYTE *CommHardware; Pointer to the hardware type (FAXONLY or HASCCC). If HASCCC, the destination is a Connection CoProcessor and can receive both faxes and file transfers. Errors For a listing of the Pberrno numbers and associated messages, refer to PBERROR.H. Return Value Returns SUCCESS if the indicated entry was found in the phonebook. Otherwise, returns FAIL. Remarks If recordID is -1, the function finds the entry for the given name and fills in the PhoneNumber, CommHardware and recordID parameters. If recordID is set to a valid record ID (0 -999), this function finds the entry with that record ID, and fills the name parameter as well as PhoneNumber and CommHardware. If the name was used for the lookup, it must be exact, except for case. (The PbFindFirstOrNext function does wildcard searching.) 6-24 PBLIB: Library For Phonebook Management PbLookUpSendInfo NOTE: You must open the phonebook with PbOpenPhonebook before you can use this function. See Also PbOpenPhonebook, PbFindFirstOrNext, PbGetEntry Example Program The following program looks up and displays the information needed for sending the requested entry in the default phonebook. #include <stdio.h> #include <phonebk.h> #include <pberror.h> #include <pbglobal.h> char *pbname = "c:\\connect\\default.pb"; main() { PB phonebook, *result; int rid = -1; BYTE hware; char name[32]; char phone[47]; if (result = PbOpenPhonebook(&phonebook, pbname)) { printf("\nEnter exact name for "); printf("minimum send info: "); gets(name); if (PbLookUpSendInfo(&phonebook, name, &rid, phone, &hware)) { PBLIB: Library For Phonebook Management 6-25 PbLookUpSendInfo printf("\nName: %s", name); printf("\nRecord ID: %4d", rid); printf("\nPhone: %s", phone); printf("\nHardware type: %d", hware); } else { printf("\nError getting send information\n"); printf("Message is %s \n", PBerrlist[Pberrno]); } fclose(phonebook.fp); } else { printf("\nError opening phonebook \n"); printf("Message is %s \n", PBerrlist[Pberrno]); } } 6-26 PBLIB: Library For Phonebook Management PbModifyEntry Description Changes one or more fields in a phonebook entry updating any other affected entries. Summary #include <phonebk.h> #include <pbglobal.h> int PbModifyEntry (pb, recordID, ChangedEntry); Input Parameters PB *pb; Pointer to a phonebook structure. int recordID; Record ID of a phonebook entry already in the phonebook. PBE *ChangedEntry; Pointer to a phonebook entry structure holding changed information for a phonebook entry. All fields can be changed except the record ID field. If the entry's length changes, the function calculates the new length and sets the length field. Output Parameter PB *pb; The OBuffer field may be updated to contain the changed entry's offset. Errors For a listing of the Pberrno numbers and associated messages, refer to PBERROR.H. Return Value Returns SUCCESS or FAIL. Function fails if it does not find an entry with the given record ID. Remarks The caller supplies a record ID and a phonebook entry structure. The function writes all the fields of that structure (except the record ID field) into the entry indicated by the recordID parameter. An application can obtain the entry structure from a call to PbGetEntry or PbFindFirstOrNext, change one or more of its fields, and call this function with that entry structure as the ChangedEntry parameter. NOTE: You must open the phonebook with PbOpenPhonebook before you can use this function. PBLIB: Library For Phonebook Management 6-27 PbModifyEntry This function does not make any changes to group entries except a name change. It also does not make changes to membership information in any entries. To make any changes to the membership of entries, use the functions PbAddToGroup and PbRemoveFromGroup. This function does not change the type of entry (person or group). See Also PbOpenPhonebook, PbGetEntry, PbFindFirstOrNext Example Program The following program modifies the phone number field of the requested entry in the default phonebook and displays a message if success. #include <stdio.h> #include <phonebk.h> #include <pberror.h> #include <pbglobal.h> char *pbname = "c:\\connect\\default.pb"; main() { PB phonebook, *result; PBE *entry; int rid = -1; char name[32]; if (result = PbOpenPhonebook(&phonebook, pbname)) { printf("\nEnter exact name of entry "); printf("you wish to change phone of: "); gets(name); if (entry = PbGetEntry(&phonebook, NULL, name, rid)) { printf("\nName : %s\n", entry->name); printf("Phone : %s\n", entry->PhoneNumber); printf("Enter new phone: "); gets(entry->PhoneNumber); rid = entry->id; if (PbModifyEntry(&phonebook, rid, entry)) { printf("Phone of %s successfully ",name); printf("changed to %s ", entry->PhoneNumber); } else { printf("Error modifying entry\n"); printf("Message is %s \n", PBerrlist[Pberrno]); } PbFreePBE(&phonebook, entry); } else { 6-28 PBLIB: Library For Phonebook Management PbModifyEntry printf("Error getting entry\n"); printf("Message is %s \n", PBerrlist[Pberrno]); } fclose(phonebook.fp); } else { printf("\nError opening phonebook \n"); printf("Message is %s \n", PBerrlist[Pberrno]); } } PBLIB: Library For Phonebook Management 6-29 PbOpenPhonebook Description Opens an existing phonebook file for query or modification. Summary #include <phonebk.h> #include <pbglobal.h> PB *PbOpenPhonebook (pb, name); Input Parameters PB *pb; NULL or pointer to a phonebook structure. char *name; Pointer to a path and filename of phonebook file. Output Parameter PB *pb; If this pointed to a phonebook structure on entry, on return it contains information about the named phonebook. If the pointer pb is NULL, the function allocates the phonebook structure from conventional memory, reads the information into that structure, and returns its pointer. Errors For a listing of the Pberrno numbers and associated messages, refer to PBERROR.H. Return Value If successful, returns a pointer to the phonebook structure. If an error occurred, the function returns NULL. Remarks The application must call this function before calling any of the other phonebook functions. There are two exceptions: PbGarbageCollect, which requires a closed phonebook and PbCreatePhonebook. This function finds, opens, and reads information from the named phonebook into the fields of a phonebook structure and returns a pointer to that structure. If a phonebook structure is provide by the pointer pb, the function fills that structure's fields with the information read. The phonebook file is opened for reading and writing. The stream pointer to the file is one of the fields of the phonebook structure returned. The buffer for offsets is initially NULL; OBufferSize and OBufferFirstRID are set to 0. 6-30 PBLIB: Library For Phonebook Management PbOpenPhonebook NOTE: To close a phonebook, close the phonebook file using fclose() on the FILE pointer field of the phonebook structure. If the application allocated the memory for the phonebook structure with malloc() or directed PbOpenPhonebook to allocate memory by setting pb to NULL, the application must free that memory using the C Library function free(). See Also PbCreatePhonebook Example Program The following program opens and closes the default phonebook. #include <stdio.h> #include <phonebk.h> #include <pberror.h> #include <pbglobal.h> main() { PB phonebook, *result; char pbname[80] = "c:\\connect\\"; char pbname[80] char *c_result printf("Enter name of phonebook: "); c_result = gets(pbname); result = PbOpenPhonebook(&phonebook, pbname); if (result) { printf("Phonebook %s has %d entries\n", pbname, phonebook.header.entries); fclose(phonebook.fp); } else { printf("OpenPhonebook error, msg is:\n%s", PBerrlist[Pberrno]); } } PBLIB: Library For Phonebook Management 6-31 PbRemoveEntry Description Deletes an existing entry and updates any other affected entries. Summary #include <phonebk.h> #include <pbglobal.h> int PbRemoveEntry (pb, recordID); Input Parameters PB *pb; Pointer to a phonebook structure. int recordID; Record ID field of a phonebook entry structure. Output Parameter PB *pb; Pointer to the modified phonebook structure. Errors For a listing of the Pberrno numbers and associated messages, refer to PBERROR.H. Return Value Returns SUCCESS if the entry was successfully deleted from the phonebook. Returns FAIL and leaves the phonebook as it was if the function cannot find an entry with the given record ID. Remarks If the entry was a member of a group or groups, its record ID is removed from those groups' membership lists. If the entry was a group, its record ID is removed from the membership lists of its members. If the entry removed is the last remaining member of a group, PbRemoveEntry also removes that group. If a group is removed, the members will still be in the phonebook but won't be a part of that group. To remove all members of a group, call PbRemoveEntry in a loop with each of the record IDs in the group's membership list. If the entry removed is a member of a group, the hardware type of the group may change. If the hardware type of the removed member is FAXONLY and all other members of the group have hardware type HASCCC, the hardware type changes to HASCCC. NOTE: You must open the phonebook with PbOpenPhonebook before you can use this function. 6-32 PBLIB: Library For Phonebook Management PbRemoveEntry See Also PbOpenPhonebook, PbRemoveFromGroup, PbGetEntry, PbFindFirstOrNext, PbFreePBE Example Program The following program finds and removes the requested entry from the default phonebook. #include <stdio.h> #include <phonebk.h> #include <pberror.h> #include <pbglobal.h> char *pbname = "c:\\connect\\default.pb"; main() { PB phonebook, *result; PBE *entry; int rid = -1; char name[32]; if (result = PbOpenPhonebook(&phonebook, pbname)) { printf("\nEnter exact name of entry "); printf("to remove from phonebook: "); gets(name); if (entry = PbGetEntry(&phonebook, NULL, name, rid)) { rid = entry->id; if (PbRemoveEntry(&phonebook, rid)) { printf("%s removed from %s", name,pbname); } else { printf("Error removing entry\n"); printf("Message is %s \n", PBerrlist[Pberrno]); } PbFreePBE(&phonebook, entry); } else { printf("Error getting entry\n"); printf("Message is %s \n", PBerrlist[Pberrno]); } fclose(phonebook.fp); } else { printf("\nError opening phonebook \n"); printf("Message is %s \n", PBerrlist[Pberrno]); } } PBLIB: Library For Phonebook Management 6-33 PbRemoveFromGroup Description Deletes a person entry from a group updating any other affected entries. Summary #include <phonebk.h> #include <pbglobal.h> int PbRemoveFromGroup (phonebook, GroupID, MemberID); Input Parameters PB *phonebook; Pointer to a phonebook structure. int GroupID; Record ID of a group phonebook entry. int MemberID; Record ID of a person phonebook entry to delete from the specified group. Output Parameter PB *phonebook; Modified phonebook structure. Errors For a listing of the Pberrno numbers and associated messages, refer to PBERROR.H. Return Value Returns SUCCESS or FAIL. Function fails if the entries don't exist, if they are not the right type (person or group), or if the person was not a member of that group. Remarks The record ID of the member is removed from the membership list of the group, and the record ID of the group is removed from the membership list of the member. If the member is the last member of the group, the function also removes the group entry. This function uses the entry's record ID numbers to access the entries. If only the names of the entries are known, the application can find the record IDs by using either PbGetEntry or PbFindFirstOrNext. NOTE: You must open the phonebook with PbOpenPhonebook before you can use this function. See Also PbOpenPhonebook, PbRemoveEntry, PbGetEntry, PbFindFirstOrNext, PbFreePBE 6-34 PBLIB: Library For Phonebook Management PbRemoveFromGroup Example Program The following program finds the requested person entry in the default phonebook and removes that person from the requested group. #include <stdio.h> #include <phonebk.h> #include <pberror.h> #include <pbglobal.h> char *pbname = "c:\\connect\\default.pb"; main() { PB phonebook, *result; PBE *person, *group; int rid = -1; char aperson[32]; char agroup[32]; if (result = PbOpenPhonebook(&phonebook, pbname)) { printf("Enter person removing from group - "); gets(aperson); printf("\nEnter group removing "); printf("person from - "); gets(agroup); if (person = PbGetEntry(&phonebook, NULL, aperson, rid)) { if (group = PbGetEntry(&phonebook, NULL, agroup, rid)) { if(PbRemoveFromGroup(&phonebook,group->id, person->id)) { printf("Successfully removed %s from "); printf("%s\n", aperson, agroup); PbFreePBE(&phonebook, group); } else { printf("\nError removing from group \n"); printf("Message is %s \n", PBerrlist[Pberrno]); } } else { printf("\nError getting group \n"); printf("Message is %s \n", PBerrlist[Pberrno]); } PbFreePBE(&phonebook, person); } else { printf("\nError getting person \n"); printf("Message is %s \n", PBerrlist[Pberrno]); } fclose(phonebook.fp); } else { printf("\nError opening phonebook \n"); printf("Message is %s \n", PBLIB: Library For Phonebook Management 6-35 PbRemoveFromGroup PBerrlist[Pberrno]); } } 6-36 PBLIB: Library For Phonebook Management TOOLKIT COMPATIBILITY A WITH TURBO C This appendix provides information on using Turbo C with the CAS and Phonebook Toolkit. NOTE: Intel has tested the Toolkit using Microsoft C 5.1. While the instructions below are provided for your convenience, Intel has not fully tested the Toolkit using Borland's Turbo C. Both the FAXLIB and PBLIB libraries were compiled using Microsoft C 5.1. Code compiled under Microsoft C cannot be linked with TLINK, (Borland's Turbo Linker) because the Microsoft C compiler uses undocumented object record formats in the .OBJ files. TLINK does not support these undocumented formats. To use the FAXLIB and PBLIB libraries with Turbo C, recompile the routines using the Turbo C compiler. NOTE: The Microsoft C include file malloc.h is called alloc.h in Turbo C. Rename malloc.h to alloc.h in all the source files before compiling. Rebuild the libraries using Borland's Turbo Librarian, TLIB. CASLIB links to applications using TLINK. The object modules (.OBJ files) in the CASLIB library are built by Microsoft Macro Assembler 5.1. Toolkit Compatibility With Turbo C A-1 A-1 Toolkit Compatibility With Turbo C